This is /home/cyd/emacs/doc/emacs/../../info/emacs, produced by
makeinfo version 4.13 from /home/cyd/emacs/doc/emacs/emacs.texi.

This is the `GNU Emacs Manual', updated for Emacs version 24.2.

Copyright (C) 1985-1987, 1993-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "The GNU Manifesto,"
     "Distribution" and "GNU GENERAL PUBLIC LICENSE," with the
     Front-Cover texts being "A GNU Manual," and with the Back-Cover
     Texts as in (a) below.  A copy of the license is included in the
     section entitled "GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs).       The extensible self-documenting text editor.
END-INFO-DIR-ENTRY


File: emacs,  Node: Sexp Diary Entries,  Prev: Fancy Diary Display,  Up: Advanced Calendar/Diary Usage

31.15.9 Sexp Entries and the Fancy Diary Display
------------------------------------------------

Sexp diary entries allow you to do more than just have complicated
conditions under which a diary entry applies.  Sexp entries should be
preceded by `diary-sexp-entry-symbol' (default `%%') in the diary file.
With the fancy diary display, sexp entries can generate the text of the
entry depending on the date itself.

   For example, an anniversary diary entry can insert the number of
years since the anniversary date into the text of the diary entry.
Thus the `%d' in this diary entry:

     %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)

gets replaced by the age, so on October 31, 1990 the entry appears in
the fancy diary buffer like this:

     Arthur's birthday (42 years old)

If the diary file instead contains this entry:

     %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday

the entry in the fancy diary buffer for October 31, 1990 appears like
this:

     Arthur's 42nd birthday

   Similarly, cyclic diary entries can interpolate the number of
repetitions that have occurred:

     %%(diary-cyclic 50 1 1 2012) Renew medication (%d%s time)

looks like this:

     Renew medication (5th time)

in the fancy diary display on September 7, 2012.

   There is an "early reminder" diary sexp that includes its entry in
the diary not only on the date of occurrence, but also on earlier dates.
For example, if you want a reminder a week before your anniversary, you
can use

     %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary

and the fancy diary will show `Ed's anniversary' both on December 15
and on December 22.

   The function `diary-date' applies to dates described by a month,
day, year combination, each of which can be an integer, a list of
integers, or `t' (meaning all values).  For example,

     %%(diary-date '(10 11 12) 22 t) Rake leaves

causes the fancy diary to show

     Rake leaves

on October 22, November 22, and December 22 of every year.

   The function `diary-float' allows you to describe diary entries that
apply to dates like the third Friday of November, or the last Tuesday
in April.  The parameters are the MONTH, DAYNAME, and an index N.  The
entry appears on the Nth DAYNAME after the first day of MONTH, where
DAYNAME=0 means Sunday, 1 means Monday, and so on.  If N is negative it
counts backward from the end of MONTH.  The value of MONTH can be a
list of months, a single month, or `t' to specify all months.  You can
also use an optional parameter DAY to specify the Nth DAYNAME on or
after/before DAY of MONTH; the value of DAY defaults to 1 if N is
positive and to the last day of MONTH if N is negative.  For example,

     %%(diary-float t 1 -1) Pay rent

causes the fancy diary to show

     Pay rent

on the last Monday of every month.

   The generality of sexp diary entries lets you specify any diary
entry that you can describe algorithmically.  A sexp diary entry
contains an expression that computes whether the entry applies to any
given date.  If its value is non-`nil', the entry applies to that date;
otherwise, it does not.  The expression can use the variable `date' to
find the date being considered; its value is a list (MONTH DAY YEAR)
that refers to the Gregorian calendar.

   The sexp diary entry applies to a date when the expression's value
is non-`nil', but some values have more specific meanings.  If the
value is a string, that string is a description of the event which
occurs on that date.  The value can also have the form `(MARK .
STRING)'; then MARK specifies how to mark the date in the calendar, and
STRING is the description of the event.  If MARK is a single-character
string, that character appears next to the date in the calendar.  If
MARK is a face name, the date is displayed in that face.  If MARK is
`nil', that specifies no particular highlighting for the date.

   Suppose you get paid on the 21st of the month if it is a weekday, and
on the Friday before if the 21st is on a weekend.  Here is how to write
a sexp diary entry that matches those dates:

     &%%(let ((dayname (calendar-day-of-week date))
              (day (cadr date)))
           (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
               (and (memq day '(19 20)) (= dayname 5)))
              ) Pay check deposited

   The following sexp diary entries take advantage of the ability (in
the fancy diary display) to concoct diary entries whose text varies
based on the date:

`%%(diary-sunrise-sunset)'
     Make a diary entry for today's local times of sunrise and sunset.

`%%(diary-lunar-phases)'
     Make a diary entry for the phases (quarters) of the moon.

`%%(diary-day-of-year)'
     Make a diary entry with today's day number in the current year and
     the number of days remaining in the current year.

`%%(diary-iso-date)'
     Make a diary entry with today's equivalent ISO commercial date.

`%%(diary-julian-date)'
     Make a diary entry with today's equivalent Julian calendar date.

`%%(diary-astro-day-number)'
     Make a diary entry with today's equivalent astronomical (Julian)
     day number.

`%%(diary-bahai-date)'
     Make a diary entry with today's equivalent Bah�'� calendar date.

`%%(diary-chinese-date)'
     Make a diary entry with today's equivalent Chinese calendar date.

`%%(diary-coptic-date)'
     Make a diary entry with today's equivalent Coptic calendar date.

`%%(diary-ethiopic-date)'
     Make a diary entry with today's equivalent Ethiopic calendar date.

`%%(diary-french-date)'
     Make a diary entry with today's equivalent date on the French
     Revolutionary calendar.

`%%(diary-hebrew-date)'
     Make a diary entry with today's equivalent Hebrew calendar date.

`%%(diary-islamic-date)'
     Make a diary entry with today's equivalent Islamic calendar date.

`%%(diary-mayan-date)'
     Make a diary entry with today's equivalent Mayan calendar date.

`%%(diary-persian-date)'
     Make a diary entry with today's equivalent Persian calendar date.

For example, including the diary entry

     &%%(diary-hebrew-date)

causes every day's diary display to contain the equivalent date on the
Hebrew calendar, if you are using the fancy diary display.  (With simple
diary display, the literal line `&%%(diary-hebrew-date)' appears in the
diary for any date.)

   This function has been used to construct certain standard Hebrew sexp
diary entries:

`%%(diary-hebrew-rosh-hodesh)'
     Make a diary entry that tells the occurrence and ritual
     announcement of each new Hebrew month.

`%%(diary-hebrew-parasha)'
     Make a Saturday diary entry that tells the weekly synagogue
     scripture reading.

`%%(diary-hebrew-sabbath-candles)'
     Make a Friday diary entry that tells the _local time_ of Sabbath
     candle lighting.

`%%(diary-hebrew-omer)'
     Make a diary entry that gives the omer count, when appropriate.

`%%(diary-hebrew-yahrzeit MONTH DAY YEAR) NAME'
     Make a diary entry marking the anniversary of a date of death.
     The date is the _Gregorian_ (civil) date of death.  The diary
     entry appears on the proper Hebrew calendar anniversary and on the
     day before.  (The order of the parameters changes according to the
     calendar date style; for example in the European style to DAY,
     MONTH, YEAR.)

`%%(diary-hebrew-birthday MONTH DAY YEAR)'
     Make a diary entry for a birthday on the Hebrew calendar.

   All the functions documented above take an optional argument MARK
which specifies how to mark the date in the calendar display.  If one
of these functions decides that it applies to a certain date, it
returns a value that contains MARK, as described above.


File: emacs,  Node: Sending Mail,  Next: Rmail,  Prev: Calendar/Diary,  Up: Top

32 Sending Mail
***************

To send an email message from Emacs, type `C-x m'.  This switches to a
buffer named `*unsent mail*', where you can edit the text and headers
of the message.  When done, type `C-c C-s' or `C-c C-c' to send it.

`C-x m'
     Begin composing mail (`compose-mail').

`C-x 4 m'
     Likewise, in another window (`compose-mail-other-window').

`C-x 5 m'
     Likewise, but in a new frame (`compose-mail-other-frame').

`C-c C-s'
     In the mail buffer, send the message (`message-send').

`C-c C-c'
     In the mail buffer, send the message and bury the buffer
     (`message-send-and-exit').

   The mail buffer is an ordinary Emacs buffer, so you can switch to
other buffers while composing the mail.  If you want to send another
mail before finishing the current one, type `C-x m' again to open a new
mail buffer whose name has a different numeric suffix (*note Misc
Buffer::).  If you invoke the command with a prefix argument,
`C-u C-x m', Emacs switches back to the last mail buffer, and asks if
you want to erase the message in that buffer; if you answer no, this
lets you pick up editing the message where you left off.

   The command `C-x 4 m' (`compose-mail-other-window') does the same as
`C-x m', except it displays the mail buffer in a different window.  The
command `C-x 5 m' (`compose-mail-other-frame') does it in a new frame.

   When you type `C-c C-c' or `C-c C-s' to send the mail, Emacs may ask
you how it should deliver the mail--either directly via SMTP, or using
some other method.  *Note Mail Sending::, for details.

* Menu:

* Format: Mail Format.        Format of a mail message.
* Headers: Mail Headers.      Details of some standard mail header fields.
* Aliases: Mail Aliases.      Abbreviating and grouping mail addresses.
* Commands: Mail Commands.    Special commands for editing mail being composed.
* Signature: Mail Signature.  Adding a signature to every message.
* Amuse: Mail Amusements.     Distracting the NSA; adding fortune messages.
* Methods: Mail Methods.      Using alternative mail-composition methods.


File: emacs,  Node: Mail Format,  Next: Mail Headers,  Up: Sending Mail

32.1 The Format of the Mail Buffer
==================================

Here is an example of the contents of a mail buffer:

     To: subotai@example.org
     CC: mongol.soldier@example.net, rms@gnu.org
     Subject: Re: What is best in life?
     From: conan@example.org
     --text follows this line--
     To crush your enemies, see them driven before you, and to
     hear the lamentation of their women.

At the top of the mail buffer is a set of "header fields", which are
used for specifying information about the email's recipient(s),
subject, and so on.  The above buffer contains header fields for `To',
`Cc', `Subject', and `From'.  Some header fields are automatically
pre-initialized in the mail buffer, when appropriate.

   The line that says `--text follows this line--' separates the header
fields from the "body" (or "text") of the message.  Everything above
that line is treated as part of the headers; everything below it is
treated as the body.  The delimiter line itself does not appear in the
message actually sent.

   You can insert and edit header fields using ordinary editing
commands.  *Note Header Editing::, for commands specific to editing
header fields.  Certain headers, such as `Date' and `Message-Id', are
normally omitted from the mail buffer and are created automatically
when the message is sent.


File: emacs,  Node: Mail Headers,  Next: Mail Aliases,  Prev: Mail Format,  Up: Sending Mail

32.2 Mail Header Fields
=======================

A header field in the mail buffer starts with a field name at the
beginning of a line, terminated by a colon.  Upper and lower case are
equivalent in field names.  After the colon and optional whitespace
comes the contents of the field.

   You can use any name you like for a header field, but normally
people use only standard field names with accepted meanings.

   The `From' header field identifies the person sending the email
(i.e. you).  This should be a valid mailing address, as replies are
normally sent there.  The default contents of this header field are
computed from the variables `user-full-name' (which specifies your full
name) and `user-mail-address' (your email address).  On some operating
systems, Emacs initializes these two variables using environment
variables (*note General Variables::).  If this information is
unavailable or wrong, you should customize the variables yourself
(*note Easy Customization::).

   The value of the variable `mail-from-style' specifies how to format
the contents of the `From' field:

`nil'
     Use just the address, as in `king@grassland.com'.

`parens'
     Use both address and full name, as in:
     `king@grassland.com (Elvis Parsley)'.

`angles'
     Use both address and full name, as in:
     `Elvis Parsley <king@grassland.com>'.

any other value
     Use `angles' normally.  But if the address must be "quoted" to
     remain syntactically valid under the `angles' format but not under
     the `parens' format, use `parens' instead.  This is the default.

   Apart from `From', here is a table of commonly-used fields:

`To'
     The mailing address(es) to which the message is addressed.  To list
     more than one address, use commas to separate them.

`Subject'
     The subject of the message.

`CC'
     Additional mailing address(es) to send the message to.  This is
     like `To', except that these readers should not regard the message
     as directed at them.

`BCC'
     Additional mailing address(es) to send the message to, which should
     not appear in the header of the message actually sent.  "BCC"
     stands for "blind carbon copies".

`FCC'
     The name of a file, to which a copy of the sent message should be
     appended.  Emacs writes the message in mbox format, unless the
     file is in Babyl format (used by Rmail before Emacs 23), in which
     case Emacs writes in Babyl format.  If an Rmail buffer is visiting
     the file, Emacs updates it accordingly.  To specify more than one
     file, use several `FCC' fields, with one file name in each field.

`Reply-to'
     An address to which replies should be sent, instead of `From'.
     This is used if, for some reason, your `From' address cannot
     receive replies.

`Mail-reply-to'
     This field takes precedence over `Reply-to'.  It is used because
     some mailing lists set the `Reply-to' field for their own purposes
     (a somewhat controversial practice).

`Mail-followup-to'
     One of more address(es) to use as default recipient(s) for
     follow-up messages.  This is typically used when you reply to a
     message from a mailing list that you are subscribed to, and want
     replies to go to the list without sending an extra copy to you.

`In-reply-to'
     An identifier for the message you are replying to.  Most mail
     readers use this information to group related messages together.
     Normally, this header is filled in automatically when you reply to
     a message in any mail program built into Emacs.

`References'
     Identifiers for previous related messages.  Like `In-reply-to',
     this is normally filled in automatically for you.

The `To', `CC', and `BCC' fields can appear any number of times, and
each such header field can contain multiple addresses, separated by
commas.  This way, you can specify any number of places to send the
message.  These fields can also have continuation lines: one or more
lines starting with whitespace, following the starting line of the
field, are considered part of the field.  Here's an example of a `To'
field with a continuation line:

     To: foo@example.net, this@example.net,
       bob@example.com

   You can direct Emacs to insert certain default headers into the mail
buffer by setting the variable `mail-default-headers' to a string.
Then `C-x m' inserts this string into the message headers.  For
example, here is how to add a `Reply-to' and `FCC' header to each
message:

     (setq mail-default-headers
           "Reply-to: foo@example.com\nFCC: ~/Mail/sent")

If the default header fields are not appropriate for a particular
message, edit them as necessary before sending the message.


File: emacs,  Node: Mail Aliases,  Next: Mail Commands,  Prev: Mail Headers,  Up: Sending Mail

32.3 Mail Aliases
=================

You can define "mail aliases", which are short mnemonic names that
stand for one or more mailing addresses.  By default, mail aliases are
defined in the file `~/.mailrc'.  You can specify a different file name
to use, by setting the variable `mail-personal-alias-file'.

   To define an alias in `.mailrc', write a line like this:

     alias NICK FULLADDRESSES

This means that NICK should expand into FULLADDRESSES, where
FULLADDRESSES can be either a single address, or multiple addresses
separated with spaces.  For instance, to make `maingnu' stand for
`gnu@gnu.org' plus a local address of your own, put in this line:

     alias maingnu gnu@gnu.org local-gnu

If an address contains a space, quote the whole address with a pair of
double quotes, like this:

     alias jsmith "John Q. Smith <none@example.com>"

Note that you need not include double quotes around individual parts of
the address, such as the person's full name.  Emacs puts them in if
they are needed.  For instance, it inserts the above address as `"John
Q. Smith" <none@example.com>'.

   Emacs also recognizes "include" commands in `.mailrc'.  They look
like this:

     source FILENAME

The `.mailrc' file is not unique to Emacs; many other mail-reading
programs use it for mail aliases, and it can contain various other
commands.  However, Emacs ignores everything except alias definitions
and include commands.

   Mail aliases expand as abbrevs--that is to say, as soon as you type
a word-separator character after an alias (*note Abbrevs::).  This
expansion takes place only within the `To', `From', `CC', `BCC', and
`Reply-to' header fields (plus their `Resent-' variants); it does not
take place in other header fields, such as `Subject'.

   You can also insert an aliased address directly, using the command
`M-x mail-abbrev-insert-alias'.  This reads an alias name, with
completion, and inserts its definition at point.


File: emacs,  Node: Mail Commands,  Next: Mail Signature,  Prev: Mail Aliases,  Up: Sending Mail

32.4 Mail Commands
==================

The default major mode for the `*mail*' buffer is called Message mode.
It behaves like Text mode in many ways, but provides several additional
commands on the `C-c' prefix, which make editing a message more
convenient.

   In this section, we will describe some of the most commonly-used
commands available in Message mode.  Message mode also has its own
manual, where its features are described in greater detail.  *Note
Message: (message)Top.

* Menu:

* Mail Sending::        Commands to send the message.
* Header Editing::      Commands to move to header fields and edit them.
* Citing Mail::         Quoting a message you are replying to.
* Mail Misc::           Attachments, spell checking, etc.


File: emacs,  Node: Mail Sending,  Next: Header Editing,  Up: Mail Commands

32.4.1 Mail Sending
-------------------

`C-c C-c'
     Send the message, and bury the mail buffer
     (`message-send-and-exit').

`C-c C-s'
     Send the message, and leave the mail buffer selected
     (`message-send').

   The usual command to send a message is `C-c C-c'
(`mail-send-and-exit').  This sends the message and then "buries" the
mail buffer, putting it at the lowest priority for reselection.  If you
want it to kill the mail buffer instead, change the variable
`message-kill-buffer-on-exit' to `t'.

   The command `C-c C-s' (`message-send') sends the message and leaves
the buffer selected.  Use this command if you want to modify the
message (perhaps with new recipients) and send it again.

   Sending a message runs the hook `message-send-hook'.  It also marks
the mail buffer as unmodified, except if the mail buffer is also a
file-visiting buffer (in that case, only saving the file does that, and
you don't get a warning if you try to send the same message twice).

   The variable `send-mail-function' controls how the message is
delivered.  Its value should be one of the following functions:

`sendmail-query-once'
     Query for a delivery method (one of the other entries in this
     list), and use that method for this message; then save the method
     to `send-mail-function', so that it is used for future deliveries.
     This is the default, unless you have already set the variables for
     sending mail via `smtpmail-send-it' (see below).

`smtpmail-send-it'
     Send mail using the through an external mail host, such as your
     Internet service provider's outgoing SMTP mail server.  If you have
     not told Emacs how to contact the SMTP server, it prompts for this
     information, which is saved in the `smtpmail-smtp-server' variable
     and the file `~/.authinfo'.  *Note Emacs SMTP Library:
     (smtpmail)Top.

`sendmail-send-it'
     Send mail using the system's default `sendmail' program, or
     equivalent.  This requires the system to be set up for delivering
     mail directly via SMTP.

`mailclient-send-it'
     Pass the mail buffer on to the system's designated mail client.
     See the commentary section in the file `mailclient.el' for details.

`feedmail-send-it'
     This is similar to `sendmail-send-it', but allows you to queue
     messages for later sending.  See the commentary section in the file
     `feedmail.el' for details.

   When you send a message containing non-ASCII characters, they need
to be encoded with a coding system (*note Coding Systems::).  Usually
the coding system is specified automatically by your chosen language
environment (*note Language Environments::).  You can explicitly
specify the coding system for outgoing mail by setting the variable
`sendmail-coding-system' (*note Recognize Coding::).  If the coding
system thus determined does not handle the characters in a particular
message, Emacs asks you to select the coding system to use, showing a
list of possible coding systems.


File: emacs,  Node: Header Editing,  Next: Citing Mail,  Prev: Mail Sending,  Up: Mail Commands

32.4.2 Mail Header Editing
--------------------------

Message mode provides the following special commands to move to
particular header fields and to complete addresses in headers.

`C-c C-f C-t'
     Move to the `To' header (`message-goto-to').

`C-c C-f C-s'
     Move to the `Subject' header (`message-goto-subject').

`C-c C-f C-c'
     Move to the `CC' header (`message-goto-cc').

`C-c C-f C-b'
     Move to the `BCC' header (`message-goto-bcc').

`C-c C-f C-r'
     Move to the `Reply-To' header (`message-goto-reply-to').

`C-c C-f C-f'
     Move to the `Mail-Followup-To' header field
     (`message-goto-followup-to').

`C-c C-f C-w'
     Add a new `FCC' header field, with file-name completion
     (`message-goto-fcc').

`C-c C-b'
     Move to the start of the message body (`message-goto-body').

`<TAB>'
     Complete a mailing address (`message-tab').

   The commands to move point to particular header fields are all based
on the prefix `C-c C-f' (`C-f' is for "field").  If the field in
question does not exist, the command creates one (the exception is
`mail-fcc', which creates a new field each time).

   The command `C-c C-b' (`message-goto-body') moves point to just
after the header separator line--that is, to the beginning of the body.

   While editing a header field that contains addresses, such as `To:',
`CC:' and `BCC:', you can complete an address by typing <TAB>
(`message-tab').  This attempts to insert the full name corresponding
to the address based on a couple of methods, including EUDC, a library
that recognizes a number of directory server protocols (*note EUDC:
(eudc)Top.).  Failing that, it attempts to expand the address as a mail
alias (*note Mail Aliases::).  If point is on a header field that does
not take addresses, or if it is in the message body, then <TAB> just
inserts a tab character.


File: emacs,  Node: Citing Mail,  Next: Mail Misc,  Prev: Header Editing,  Up: Mail Commands

32.4.3 Citing Mail
------------------

`C-c C-y'
     Yank the selected message from the mail reader, as a citation
     (`message-yank-original').

`C-c C-q'
     Fill each paragraph cited from another message
     (`message-fill-yanked-message').

   You can use the command `C-c C-y' (`message-yank-original') to
"cite" a message that you are replying to.  This inserts the text of
that message into the mail buffer.  This command works only if the mail
buffer is invoked from a mail reader running in Emacs, such as Rmail.

   By default, Emacs inserts the string `>' in front of each line of
the cited text; this prefix string is specified by the variable
`message-yank-prefix'.  If you call `message-yank-original' with a
prefix argument, the citation prefix is not inserted.

   After using `C-c C-y', you can type `C-c C-q'
(`message-fill-yanked-message') to fill the paragraphs of the cited
message.  One use of `C-c C-q' fills all such paragraphs, each one
individually.  To fill a single paragraph of the quoted message, use
`M-q'.  If filling does not automatically handle the type of citation
prefix you use, try setting the fill prefix explicitly.  *Note
Filling::.

   You can customize mail citation through the hook
`mail-citation-hook'.  For example, you can use the Supercite package,
which provides more flexible citation (*note Introduction:
(sc)Introduction.).


File: emacs,  Node: Mail Misc,  Prev: Citing Mail,  Up: Mail Commands

32.4.4 Mail Miscellany
----------------------

You can "attach" a file to an outgoing message by typing `C-c C-a'
(`mml-attach-file') in the mail buffer.  Attaching is done using the
Multipurpose Internet Mail Extensions (MIME) standard.

   The `mml-attach-file' command prompts for the name of the file, and
for the attachment's "content type", "description", and "disposition".
The content type is normally detected automatically; just type <RET> to
accept the default.  The description is a single line of text that the
recipient will see next to the attachment; you may also choose to leave
this empty.  The disposition is either `inline' (the default), which
means the recipient will see a link to the attachment within the
message body, or `attachment', which means the link will be separate
from the body.

   The `mml-attach-file' command is specific to Message mode; in Mail
mode use `mail-add-attachment' instead.  It will prompt only for the
name of the file, and will determine the content type and the
disposition automatically.  If you want to include some description of
the attached file, type that in the message body.

   The actual contents of the attached file are not inserted into the
mail buffer.  Instead, some placeholder text is inserted into the mail
buffer, like this:

     <#part type="text/plain" filename="~/foo.txt" disposition=inline>
     <#/part>

When you type `C-c C-c' or `C-c C-s' to send the message, the attached
file will be delivered with it.

   While composing a message, you can do spelling correction on the
message text by typing `M-x ispell-message'.  If you have yanked an
incoming message into the outgoing draft, this command skips what was
yanked, but it checks the text that you yourself inserted (it looks for
indentation or `mail-yank-prefix' to distinguish the cited lines from
your input).  *Note Spelling::.

   Turning on Message mode (which `C-x m' does automatically) runs the
normal hooks `text-mode-hook' and `message-mode-hook'.  Initializing a
new outgoing message runs the normal hook `message-setup-hook'; you can
use this hook if you want to make changes to the appearance of the mail
buffer.  *Note Hooks::.

   The main difference between these hooks is just when they are
invoked.  Whenever you type `C-x m', `message-mode-hook' runs as soon
as the mail buffer is created.  Then the `message-setup' function
inserts the default contents of the buffer.  After these default
contents are inserted, `message-setup-hook' runs.

   If you use `C-x m' to continue an existing composition,
`message-mode-hook' runs immediately after switching to the mail
buffer.  If the buffer is unmodified, or if you decide to erase it and
start again, `message-setup-hook' runs after the default contents are
inserted.


File: emacs,  Node: Mail Signature,  Next: Mail Amusements,  Prev: Mail Commands,  Up: Sending Mail

32.5 Mail Signature
===================

You can add a standard piece of text--your "mail signature"--to the end
of every message.  This signature may contain information such as your
telephone number or your physical location.  The variable
`mail-signature' determines how Emacs handles the mail signature.

   The default value of `mail-signature' is `t'; this means to look for
your mail signature in the file `~/.signature'.  If this file exists,
its contents are automatically inserted into the end of the mail
buffer.  You can change the signature file via the variable
`mail-signature-file'.

   If you change `mail-signature' to a string, that specifies the text
of the signature directly.

   If you change `mail-signature' to `nil', Emacs will not insert your
mail signature automatically.  You can insert your mail signature by
typing `C-c C-w' (`message-insert-signature') in the mail buffer.
Emacs will look for your signature in the signature file.

   By convention, a mail signature should be marked by a line whose
contents are `-- '.  If your signature lacks this prefix, it is added
for you.  The remainder of your signature should be no more than four
lines.


File: emacs,  Node: Mail Amusements,  Next: Mail Methods,  Prev: Mail Signature,  Up: Sending Mail

32.6 Mail Amusements
====================

`M-x spook' adds a line of randomly chosen keywords to an outgoing mail
message.  The keywords are chosen from a list of words that suggest you
are discussing something subversive.

   The idea behind this feature is the suspicion that the NSA(1) and
other intelligence agencies snoop on all electronic mail messages that
contain keywords suggesting they might find them interesting.  (The
agencies say that they don't, but that's what they _would_ say.)  The
idea is that if lots of people add suspicious words to their messages,
the agencies will get so busy with spurious input that they will have
to give up reading it all.  Whether or not this is true, it at least
amuses some people.

   You can use the `fortune' program to put a "fortune cookie" message
into outgoing mail.  To do this, add `fortune-to-signature' to
`mail-setup-hook':

     (add-hook 'mail-setup-hook 'fortune-to-signature)

You will probably need to set the variable `fortune-file' before using
this.

   ---------- Footnotes ----------

   (1) The US National Security Agency.


File: emacs,  Node: Mail Methods,  Prev: Mail Amusements,  Up: Sending Mail

32.7 Mail-Composition Methods
=============================

In this chapter we have described the usual Emacs mode for editing and
sending mail--Message mode.  This is only one of several available
modes.  Prior to Emacs 23.2, the default mode was Mail mode, which is
similar to Message mode in many respects but lacks features such as
MIME support.  Another available mode is MH-E (*note MH-E: (mh-e)Top.).

   You can choose any of these "mail user agents" as your preferred
method for editing and sending mail.  The commands `C-x m', `C-x 4 m'
and `C-x 5 m' use whichever agent you have specified; so do various
other parts of Emacs that send mail, such as the bug reporter (*note
Bugs::).  To specify a mail user agent, customize the variable
`mail-user-agent'.  Currently, legitimate values include
`message-user-agent' (Message mode) `sendmail-user-agent' (Mail mode),
`gnus-user-agent', and `mh-e-user-agent'.

   If you select a different mail-composition method, the information
in this chapter about the mail buffer and Message mode does not apply;
the other methods use a different format of text in a different buffer,
and their commands are different as well.

   Similarly, to specify your preferred method for reading mail,
customize the variable `read-mail-command'.  The default is `rmail'
(*note Rmail::).


File: emacs,  Node: Rmail,  Next: Gnus,  Prev: Sending Mail,  Up: Top

33 Reading Mail with Rmail
**************************

Rmail is an Emacs subsystem for reading and disposing of mail that you
receive.  Rmail stores mail messages in files called Rmail files.
Reading the messages in an Rmail file is done in a special major mode,
Rmail mode, which redefines most letters to run commands for managing
mail.

* Menu:

* Basic: Rmail Basics.       Basic concepts of Rmail, and simple use.
* Scroll: Rmail Scrolling.   Scrolling through a message.
* Motion: Rmail Motion.      Moving to another message.
* Deletion: Rmail Deletion.  Deleting and expunging messages.
* Inbox: Rmail Inbox.        How mail gets into the Rmail file.
* Files: Rmail Files.        Using multiple Rmail files.
* Output: Rmail Output.      Copying messages out to files.
* Labels: Rmail Labels.      Classifying messages by labeling them.
* Attrs: Rmail Attributes.   Certain standard labels, called attributes.
* Reply: Rmail Reply.        Sending replies to messages you are viewing.
* Summary: Rmail Summary.    Summaries show brief info on many messages.
* Sort: Rmail Sorting.       Sorting messages in Rmail.
* Display: Rmail Display.    How Rmail displays a message; customization.
* Coding: Rmail Coding.      How Rmail handles decoding character sets.
* Editing: Rmail Editing.    Editing message text and headers in Rmail.
* Digest: Rmail Digest.      Extracting the messages from a digest message.
* Rot13: Rmail Rot13.        Reading messages encoded in the rot13 code.
* Movemail::                 More details of fetching new mail.
* Remote Mailboxes::         Retrieving mail from remote mailboxes.
* Other Mailbox Formats::    Retrieving mail from local mailboxes in
                             various formats.


File: emacs,  Node: Rmail Basics,  Next: Rmail Scrolling,  Up: Rmail

33.1 Basic Concepts of Rmail
============================

Using Rmail in the simplest fashion, you have one Rmail file `~/RMAIL'
in which all of your mail is saved.  It is called your "primary Rmail
file".  The command `M-x rmail' reads your primary Rmail file, merges
new mail in from your inboxes, displays the first message you haven't
read yet, and lets you begin reading.  The variable `rmail-file-name'
specifies the name of the primary Rmail file.

   Rmail displays only one message in the Rmail file at a time.  The
message that is shown is called the "current message".  Rmail mode's
special commands can do such things as delete the current message, copy
it into another file, send a reply, or move to another message.  You
can also create multiple Rmail files and use Rmail to move messages
between them.

   Within the Rmail file, messages are normally arranged sequentially in
order of receipt; you can specify other ways to sort them (*note Rmail
Sorting::).  Messages are identified by consecutive integers which are
their "message numbers".  The number of the current message is
displayed in Rmail's mode line, followed by the total number of messages
in the file.  You can move to a message by specifying its message number
with the `j' key (*note Rmail Motion::).

   Following the usual conventions of Emacs, changes in an Rmail file
become permanent only when you save the file.  You can save it with `s'
(`rmail-expunge-and-save'), which also expunges deleted messages from
the file first (*note Rmail Deletion::).  To save the file without
expunging, use `C-x C-s'.  Rmail also saves the Rmail file after
merging new mail from an inbox file (*note Rmail Inbox::).

   You can exit Rmail with `q' (`rmail-quit'); this expunges and saves
the Rmail file, then buries the Rmail buffer as well as its summary
buffer, if present (*note Rmail Summary::).  But there is no need to
"exit" formally.  If you switch from Rmail to editing in other buffers,
and never switch back, you have exited.  Just make sure to save the
Rmail file eventually (like any other file you have changed).  `C-x s'
is a suitable way to do this (*note Save Commands::).  The Rmail
command `b', `rmail-bury', buries the Rmail buffer and its summary
without expunging and saving the Rmail file.


File: emacs,  Node: Rmail Scrolling,  Next: Rmail Motion,  Prev: Rmail Basics,  Up: Rmail

33.2 Scrolling Within a Message
===============================

When Rmail displays a message that does not fit on the screen, you must
scroll through it to read the rest.  You could do this with `C-v',
`M-v' and `M-<', but in Rmail scrolling is so frequent that it deserves
to be easier.

`<SPC>'
     Scroll forward (`scroll-up-command').

`<DEL>'
     Scroll backward (`scroll-down-command').

`.'
     Scroll to start of message (`rmail-beginning-of-message').

`/'
     Scroll to end of message (`rmail-end-of-message').

   Since the most common thing to do while reading a message is to
scroll through it by screenfuls, Rmail makes <SPC> and <DEL> do the
same as `C-v' (`scroll-up-command') and `M-v' (`scroll-down-command')
respectively.

   The command `.' (`rmail-beginning-of-message') scrolls back to the
beginning of the selected message.  This is not quite the same as `M-<':
for one thing, it does not set the mark; for another, it resets the
buffer boundaries of the current message if you have changed them.
Similarly, the command `/' (`rmail-end-of-message') scrolls forward to
the end of the selected message.


File: emacs,  Node: Rmail Motion,  Next: Rmail Deletion,  Prev: Rmail Scrolling,  Up: Rmail

33.3 Moving Among Messages
==========================

The most basic thing to do with a message is to read it.  The way to do
this in Rmail is to make the message current.  The usual practice is to
move sequentially through the file, since this is the order of receipt
of messages.  When you enter Rmail, you are positioned at the first
message that you have not yet made current (that is, the first one that
has the `unseen' attribute; *note Rmail Attributes::).  Move forward to
see the other new messages; move backward to re-examine old messages.

`n'
     Move to the next nondeleted message, skipping any intervening
     deleted messages (`rmail-next-undeleted-message').

`p'
     Move to the previous nondeleted message
     (`rmail-previous-undeleted-message').

`M-n'
     Move to the next message, including deleted messages
     (`rmail-next-message').

`M-p'
     Move to the previous message, including deleted messages
     (`rmail-previous-message').

`C-c C-n'
     Move to the next message with the same subject as the current one
     (`rmail-next-same-subject').

`C-c C-p'
     Move to the previous message with the same subject as the current
     one (`rmail-previous-same-subject').

`j'
     Move to the first message.  With argument N, move to message
     number N (`rmail-show-message').

`>'
     Move to the last message (`rmail-last-message').

`<'
     Move to the first message (`rmail-first-message').

`M-s REGEXP <RET>'
     Move to the next message containing a match for REGEXP
     (`rmail-search').

`- M-s REGEXP <RET>'
     Move to the previous message containing a match for REGEXP.

   `n' and `p' are the usual way of moving among messages in Rmail.
They move through the messages sequentially, but skip over deleted
messages, which is usually what you want to do.  Their command
definitions are named `rmail-next-undeleted-message' and
`rmail-previous-undeleted-message'.  If you do not want to skip deleted
messages--for example, if you want to move to a message to undelete
it--use the variants `M-n' and `M-p' (`rmail-next-message' and
`rmail-previous-message').  A numeric argument to any of these commands
serves as a repeat count.

   In Rmail, you can specify a numeric argument by typing just the
digits.  You don't need to type `C-u' first.

   The `M-s' (`rmail-search') command is Rmail's version of search.
The usual incremental search command `C-s' works in Rmail, but it
searches only within the current message.  The purpose of `M-s' is to
search for another message.  It reads a regular expression (*note
Regexps::) nonincrementally, then searches starting at the beginning of
the following message for a match.  It then selects that message.  If
REGEXP is empty, `M-s' reuses the regexp used the previous time.

   To search backward in the file for another message, give `M-s' a
negative argument.  In Rmail you can do this with `- M-s'.  This begins
searching from the end of the previous message.

   It is also possible to search for a message based on labels.  *Note
Rmail Labels::.

   The `C-c C-n' (`rmail-next-same-subject') command moves to the next
message with the same subject as the current one.  A prefix argument
serves as a repeat count.  With a negative argument, this command moves
backward, acting like `C-c C-p' (`rmail-previous-same-subject').  When
comparing subjects, these commands ignore the prefixes typically added
to the subjects of replies.

   To move to a message specified by absolute message number, use `j'
(`rmail-show-message') with the message number as argument.  With no
argument, `j' selects the first message.  `<' (`rmail-first-message')
also selects the first message.  `>' (`rmail-last-message') selects the
last message.


File: emacs,  Node: Rmail Deletion,  Next: Rmail Inbox,  Prev: Rmail Motion,  Up: Rmail

33.4 Deleting Messages
======================

When you no longer need to keep a message, you can "delete" it.  This
flags it as ignorable, and some Rmail commands pretend it is no longer
present; but it still has its place in the Rmail file, and still has its
message number.

   "Expunging" the Rmail file actually removes the deleted messages.
The remaining messages are renumbered consecutively.

`d'
     Delete the current message, and move to the next nondeleted message
     (`rmail-delete-forward').

`C-d'
     Delete the current message, and move to the previous nondeleted
     message (`rmail-delete-backward').

`u'
     Undelete the current message, or move back to the previous deleted
     message and undelete it (`rmail-undelete-previous-message').

`x'
     Expunge the Rmail file (`rmail-expunge').

   There are two Rmail commands for deleting messages.  Both delete the
current message and select another.  `d' (`rmail-delete-forward') moves
to the following message, skipping messages already deleted, while
`C-d' (`rmail-delete-backward') moves to the previous nondeleted
message.  If there is no nondeleted message to move to in the specified
direction, the message that was just deleted remains current.  `d' with
a prefix argument is equivalent to `C-d'.  Note that the Rmail summary
versions of these commands behave slightly differently (*note Rmail
Summary Edit::).

   Whenever Rmail deletes a message, it runs the hook
`rmail-delete-message-hook'.  When the hook functions are invoked, the
message has been marked deleted, but it is still the current message in
the Rmail buffer.

   To make all the deleted messages finally vanish from the Rmail file,
type `x' (`rmail-expunge').  Until you do this, you can still
"undelete" the deleted messages.  The undeletion command, `u'
(`rmail-undelete-previous-message'), is designed to cancel the effect
of a `d' command in most cases.  It undeletes the current message if
the current message is deleted.  Otherwise it moves backward to
previous messages until a deleted message is found, and undeletes that
message.

   You can usually undo a `d' with a `u' because the `u' moves back to
and undeletes the message that the `d' deleted.  But this does not work
when the `d' skips a few already-deleted messages that follow the
message being deleted; then the `u' command undeletes the last of the
messages that were skipped.  There is no clean way to avoid this
problem.  However, by repeating the `u' command, you can eventually get
back to the message that you intend to undelete.  You can also select a
particular deleted message with the `M-p' command, then type `u' to
undelete it.

   A deleted message has the `deleted' attribute, and as a result
`deleted' appears in the mode line when the current message is deleted.
In fact, deleting or undeleting a message is nothing more than adding
or removing this attribute.  *Note Rmail Attributes::.


File: emacs,  Node: Rmail Inbox,  Next: Rmail Files,  Prev: Rmail Deletion,  Up: Rmail

33.5 Rmail Files and Inboxes
============================

When you receive mail locally, the operating system places incoming
mail for you in a file that we call your "inbox".  When you start up
Rmail, it runs a C program called `movemail' to copy the new messages
from your local inbox into your primary Rmail file, which also contains
other messages saved from previous Rmail sessions.  It is in this file
that you actually read the mail with Rmail.  This operation is called
"getting new mail".  You can get new mail at any time in Rmail by
typing `g'.

   The variable `rmail-primary-inbox-list' contains a list of the files
that are inboxes for your primary Rmail file.  If you don't set this
variable explicitly, Rmail uses the `MAIL' environment variable, or, as
a last resort, a default inbox based on `rmail-spool-directory'.  The
default inbox file depends on your operating system; often it is
`/var/mail/USERNAME', `/var/spool/mail/USERNAME', or
`/usr/spool/mail/USERNAME'.

   You can specify the inbox file(s) for any Rmail file for the current
session with the command `set-rmail-inbox-list'; see *note Rmail
Files::.

   There are two reasons for having separate Rmail files and inboxes.

  1. The inbox file format varies between operating systems and
     according to the other mail software in use.  Only one part of
     Rmail needs to know about the alternatives, and it need only
     understand how to convert all of them to Rmail's own format.

  2. It is very cumbersome to access an inbox file without danger of
     losing mail, because it is necessary to interlock with mail
     delivery.  Moreover, different operating systems use different
     interlocking techniques.  The strategy of moving mail out of the
     inbox once and for all into a separate Rmail file avoids the need
     for interlocking in all the rest of Rmail, since only Rmail
     operates on the Rmail file.

   Rmail was originally written to use the Babyl format as its internal
format.  Since then, we have recognized that the usual inbox format
(`mbox') on Unix and GNU systems is adequate for the job, and so since
Emacs 23 Rmail uses that as its internal format.  The Rmail file is
still separate from the inbox file, even though their format is the
same.

   When getting new mail, Rmail first copies the new mail from the
inbox file to the Rmail file; then it saves the Rmail file; then it
clears out the inbox file.  This way, a system crash may cause
duplication of mail between the inbox and the Rmail file, but cannot
lose mail.  If `rmail-preserve-inbox' is non-`nil', then Rmail does not
clear out the inbox file when it gets new mail.  You may wish to set
this, for example, on a portable computer you use to check your mail
via POP while traveling, so that your mail will remain on the server
and you can save it later on your workstation.

   In some cases, Rmail copies the new mail from the inbox file
indirectly.  First it runs the `movemail' program to move the mail from
the inbox to an intermediate file called `.newmail-INBOXNAME', in the
same directory as the Rmail file.  Then Rmail merges the new mail from
that file, saves the Rmail file, and only then deletes the intermediate
file.  If there is a crash at the wrong time, this file continues to
exist, and Rmail will use it again the next time it gets new mail from
that inbox.

   If Rmail is unable to convert the data in `.newmail-INBOXNAME' into
mbox format, it renames the file to `RMAILOSE.N' (N is an integer
chosen to make the name unique) so that Rmail will not have trouble
with the data again.  You should look at the file, find whatever
message confuses Rmail (probably one that includes the
control-underscore character, octal code 037), and delete it.  Then you
can use `1 g' to get new mail from the corrected file.


File: emacs,  Node: Rmail Files,  Next: Rmail Output,  Prev: Rmail Inbox,  Up: Rmail

33.6 Multiple Rmail Files
=========================

Rmail operates by default on your "primary Rmail file", which is named
`~/RMAIL' and receives your incoming mail from your system inbox file.
But you can also have other Rmail files and edit them with Rmail.  These
files can receive mail through their own inboxes, or you can move
messages into them with explicit Rmail commands (*note Rmail Output::).

`i FILE <RET>'
     Read FILE into Emacs and run Rmail on it (`rmail-input').

`M-x set-rmail-inbox-list <RET> FILES <RET>'
     Specify inbox file names for current Rmail file to get mail from.

`g'
     Merge new mail from current Rmail file's inboxes
     (`rmail-get-new-mail').

`C-u g FILE <RET>'
     Merge new mail from inbox file FILE.

   To run Rmail on a file other than your primary Rmail file, you can
use the `i' (`rmail-input') command in Rmail.  This visits the file in
Rmail mode.  You can use `M-x rmail-input' even when not in Rmail, but
it is easier to type `C-u M-x rmail', which does the same thing.

   The file you read with `i' should normally be a valid mbox file.  If
it is not, Rmail tries to convert its text to mbox format, and visits
the converted text in the buffer.  If you save the buffer, that
converts the file.

   If you specify a file name that doesn't exist, `i' initializes a new
buffer for creating a new Rmail file.

   You can also select an Rmail file from a menu.  In the Classify menu,
choose the Input Rmail File item; then choose the Rmail file you want.
The variables `rmail-secondary-file-directory' and
`rmail-secondary-file-regexp' specify which files to offer in the menu:
the first variable says which directory to find them in; the second
says which files in that directory to offer (all those that match the
regular expression).  If no files match, you cannot select this menu
item.  These variables also apply to choosing a file for output (*note
Rmail Output::).

   The inbox files to use are specified by the variable
`rmail-inbox-list', which is buffer-local in Rmail mode.  As a special
exception, if you have specified no inbox files for your primary Rmail
file, it uses the `MAIL' environment variable, or your standard system
inbox.

   The `g' command (`rmail-get-new-mail') merges mail into the current
Rmail file from its inboxes.  If the Rmail file has no inboxes, `g'
does nothing.  The command `M-x rmail' also merges new mail into your
primary Rmail file.

   To merge mail from a file that is not the usual inbox, give the `g'
key a numeric argument, as in `C-u g'.  Then it reads a file name and
merges mail from that file.  The inbox file is not deleted or changed
in any way when `g' with an argument is used.  This is, therefore, a
general way of merging one file of messages into another.


File: emacs,  Node: Rmail Output,  Next: Rmail Labels,  Prev: Rmail Files,  Up: Rmail

33.7 Copying Messages Out to Files
==================================

These commands copy messages from an Rmail file into another file.

`o FILE <RET>'
     Append a full copy of the current message to the file FILE
     (`rmail-output').

`C-o FILE <RET>'
     Append a copy of the current message, as displayed, to the file
     FILE (`rmail-output-as-seen').

`w FILE <RET>'
     Output just the message body to the file FILE, taking the default
     file name from the message `Subject' header.

   The commands `o' and `C-o' copy the current message into a specified
file, adding it at the end.  The two commands differ mainly in how much
to copy: `o' copies the full message headers, even if they are not all
visible, while `C-o' copies exactly the headers currently displayed and
no more.  *Note Rmail Display::.  In addition, `o' converts the message
to Babyl format (used by Rmail in Emacs version 22 and before) if the
file is in Babyl format; `C-o' cannot output to Babyl files at all.

   If the output file is currently visited in an Emacs buffer, the
output commands append the message to that buffer.  It is up to you to
save the buffer eventually in its file.

   Sometimes you may receive a message whose body holds the contents of
a file.  You can save the body to a file (excluding the message header)
with the `w' command (`rmail-output-body-to-file').  Often these
messages contain the intended file name in the `Subject' field, so the
`w' command uses the `Subject' field as the default for the output file
name.  However, the file name is read using the minibuffer, so you can
specify a different name if you wish.

   You can also output a message to an Rmail file chosen with a menu.
In the Classify menu, choose the Output Rmail File menu item; then
choose the Rmail file you want.  This outputs the current message to
that file, like the `o' command.  The variables
`rmail-secondary-file-directory' and `rmail-secondary-file-regexp'
specify which files to offer in the menu: the first variable says which
directory to find them in; the second says which files in that
directory to offer (all those that match the regular expression).  If
no files match, you cannot select this menu item.

   Copying a message with `o' or `C-o' gives the original copy of the
message the `filed' attribute, so that `filed' appears in the mode line
when such a message is current.

   If you like to keep just a single copy of every mail message, set
the variable `rmail-delete-after-output' to `t'; then the `o', `C-o'
and `w' commands delete the original message after copying it.  (You
can undelete it afterward if you wish.)

   The variable `rmail-output-file-alist' lets you specify intelligent
defaults for the output file, based on the contents of the current
message.  The value should be a list whose elements have this form:

     (REGEXP . NAME-EXP)

If there's a match for REGEXP in the current message, then the default
file name for output is NAME-EXP.  If multiple elements match the
message, the first matching element decides the default file name.  The
subexpression NAME-EXP may be a string constant giving the file name to
use, or more generally it may be any Lisp expression that returns a
file name as a string.  `rmail-output-file-alist' applies to both `o'
and `C-o'.

   Rmail can automatically save messages from your primary Rmail file
(the one that `rmail-file-name' specifies) to other files, based on the
value of the variable `rmail-automatic-folder-directives'.  This
variable is a list of elements (`directives') that say which messages
to save where.  Each directive is a list consisting of an output file,
followed by one or more pairs of a header name and a regular
expression.  If a message has a header matching the specified regular
expression, that message is saved to the given file.  If the directive
has more than one header entry, all must match.  Rmail checks directives
when it shows a message from the file `rmail-file-name', and applies
the first that matches (if any).  If the output file is `nil', the
message is deleted, not saved.  For example, you can use this feature
to save messages from a particular address, or with a particular
subject, to a dedicated file.


File: emacs,  Node: Rmail Labels,  Next: Rmail Attributes,  Prev: Rmail Output,  Up: Rmail

33.8 Labels
===========

Each message can have various "labels" assigned to it as a means of
classification.  Each label has a name; different names are different
labels.  Any given label is either present or absent on a particular
message.  A few label names have standard meanings and are given to
messages automatically by Rmail when appropriate; these special labels
are called "attributes".  (*Note Rmail Attributes::.)  All other labels
are assigned only by users.

`a LABEL <RET>'
     Assign the label LABEL to the current message (`rmail-add-label').

`k LABEL <RET>'
     Remove the label LABEL from the current message
     (`rmail-kill-label').

`C-M-n LABELS <RET>'
     Move to the next message that has one of the labels LABELS
     (`rmail-next-labeled-message').

`C-M-p LABELS <RET>'
     Move to the previous message that has one of the labels LABELS
     (`rmail-previous-labeled-message').

`l LABELS <RET>'
`C-M-l LABELS <RET>'
     Make a summary of all messages containing any of the labels LABELS
     (`rmail-summary-by-labels').

   The `a' (`rmail-add-label') and `k' (`rmail-kill-label') commands
allow you to assign or remove any label on the current message.  If the
LABEL argument is empty, it means to assign or remove the same label
most recently assigned or removed.

   Once you have given messages labels to classify them as you wish,
there are three ways to use the labels: in moving, in summaries, and in
sorting.

   `C-M-n LABELS <RET>' (`rmail-next-labeled-message') moves to the
next message that has one of the labels LABELS.  The argument LABELS
specifies one or more label names, separated by commas.  `C-M-p'
(`rmail-previous-labeled-message') is similar, but moves backwards to
previous messages.  A numeric argument to either command serves as a
repeat count.

   The command `C-M-l LABELS <RET>' (`rmail-summary-by-labels')
displays a summary containing only the messages that have at least one
of a specified set of labels.  The argument LABELS is one or more label
names, separated by commas.  *Note Rmail Summary::, for information on
summaries.

   If the LABELS argument to `C-M-n', `C-M-p' or `C-M-l' is empty, it
means to use the last set of labels specified for any of these commands.

   *Note Rmail Sorting::, for information on sorting messages with
labels.


File: emacs,  Node: Rmail Attributes,  Next: Rmail Reply,  Prev: Rmail Labels,  Up: Rmail

33.9 Rmail Attributes
=====================

Some labels such as `deleted' and `filed' have built-in meanings, and
Rmail assigns them to messages automatically at appropriate times;
these labels are called "attributes".  Here is a list of Rmail
attributes:

`unseen'
     Means the message has never been current.  Assigned to messages
     when they come from an inbox file, and removed when a message is
     made current.  When you start Rmail, it initially shows the first
     message that has this attribute.

`deleted'
     Means the message is deleted.  Assigned by deletion commands and
     removed by undeletion commands (*note Rmail Deletion::).

`filed'
     Means the message has been copied to some other file.  Assigned by
     the `o' and `C-o' file output commands (*note Rmail Output::).

`answered'
     Means you have mailed an answer to the message.  Assigned by the
     `r' command (`rmail-reply').  *Note Rmail Reply::.

`forwarded'
     Means you have forwarded the message.  Assigned by the `f' command
     (`rmail-forward').  *Note Rmail Reply::.

`edited'
     Means you have edited the text of the message within Rmail.  *Note
     Rmail Editing::.

`resent'
     Means you have resent the message.  Assigned by the command `M-x
     rmail-resend'.  *Note Rmail Reply::.

`retried'
     Means you have retried a failed outgoing message.  Assigned by the
     command `M-x rmail-retry-failure'.  *Note Rmail Reply::.

   All other labels are assigned or removed only by users, and have no
standard meaning.


File: emacs,  Node: Rmail Reply,  Next: Rmail Summary,  Prev: Rmail Attributes,  Up: Rmail

33.10 Sending Replies
=====================

Rmail has several commands to send outgoing mail.  *Note Sending
Mail::, for information on using Message mode, including certain
features meant to work with Rmail.  What this section documents are the
special commands of Rmail for entering the mail buffer.  Note that the
usual keys for sending mail--`C-x m', `C-x 4 m', and `C-x 5 m'--also
work normally in Rmail mode.

`m'
     Send a message (`rmail-mail').

`c'
     Continue editing the already started outgoing message
     (`rmail-continue').

`r'
     Send a reply to the current Rmail message (`rmail-reply').

`f'
     Forward the current message to other users (`rmail-forward').

`C-u f'
     Resend the current message to other users (`rmail-resend').

`M-m'
     Try sending a bounced message a second time
     (`rmail-retry-failure').

   The most common reason to send a message while in Rmail is to reply
to the message you are reading.  To do this, type `r' (`rmail-reply').
This displays a mail composition buffer in another window, much like
`C-x 4 m', but preinitializes the `Subject', `To', `CC', `In-reply-to'
and `References' header fields based on the message you are replying
to.  The `To' field starts out as the address of the person who sent
the message you received, and the `CC' field starts out with all the
other recipients of that message.

   You can exclude certain recipients from being included automatically
in replies, using the variable `mail-dont-reply-to-names'.  Its value
should be a regular expression; any recipients that match are excluded
from the `CC' field.  They are also excluded from the `To' field,
unless this would leave the field empty.  If this variable is nil, then
the first time you compose a reply it is initialized to a default value
that matches your own address.

   To omit the `CC' field completely for a particular reply, enter the
reply command with a numeric argument: `C-u r' or `1 r'.  This means to
reply only to the sender of the original message.

   Once the mail composition buffer has been initialized, editing and
sending the mail goes as usual (*note Sending Mail::).  You can edit
the presupplied header fields if they are not what you want.  You can
also use commands such as `C-c C-y', which yanks in the message that
you are replying to (*note Mail Commands::).  You can also switch to
the Rmail buffer, select a different message there, switch back, and
yank the new current message.

   Sometimes a message does not reach its destination.  Mailers usually
send the failed message back to you, enclosed in a "failure message".
The Rmail command `M-m' (`rmail-retry-failure') prepares to send the
same message a second time: it sets up a mail composition buffer with
the same text and header fields as before.  If you type `C-c C-c' right
away, you send the message again exactly the same as the first time.
Alternatively, you can edit the text or headers and then send it.  The
variable `rmail-retry-ignored-headers', in the same format as
`rmail-ignored-headers' (*note Rmail Display::), controls which headers
are stripped from the failed message when retrying it.

   Another frequent reason to send mail in Rmail is to "forward" the
current message to other users.  `f' (`rmail-forward') makes this easy
by preinitializing the mail composition buffer with the current message
as the text, and a subject of the form `[FROM: SUBJECT]', where FROM
and SUBJECT are the sender and subject of the original message.  All
you have to do is fill in the recipients and send.  When you forward a
message, recipients get a message which is "from" you, and which has
the original message in its contents.

   Rmail offers two formats for forwarded messages.  The default is to
use MIME (*note Rmail Display::) format.  This includes the original
message as a separate part.  You can use a simpler format if you
prefer, by setting the variable `rmail-enable-mime-composing' to `nil'.
In this case, Rmail just includes the original message enclosed between
two delimiter lines.  It also modifies every line that starts with a
dash, by inserting `- ' at the start of the line.  When you receive a
forwarded message in this format, if it contains something besides
ordinary text--for example, program source code--you might find it
useful to undo that transformation.  You can do this by selecting the
forwarded message and typing `M-x unforward-rmail-message'.  This
command extracts the original forwarded message, deleting the inserted
`- ' strings, and inserts it into the Rmail file as a separate message
immediately following the current one.

   "Resending" is an alternative similar to forwarding; the difference
is that resending sends a message that is "from" the original sender,
just as it reached you--with a few added header fields (`Resent-From'
and `Resent-To') to indicate that it came via you.  To resend a message
in Rmail, use `C-u f'.  (`f' runs `rmail-forward', which invokes
`rmail-resend' if you provide a numeric argument.)

   Use the `m' (`rmail-mail') command to start editing an outgoing
message that is not a reply.  It leaves the header fields empty.  Its
only difference from `C-x 4 m' is that it makes the Rmail buffer
accessible for `C-c C-y', just as `r' does.

   The `c' (`rmail-continue') command resumes editing the mail
composition buffer, to finish editing an outgoing message you were
already composing, or to alter a message you have sent.

   If you set the variable `rmail-mail-new-frame' to a non-`nil' value,
then all the Rmail commands to start sending a message create a new
frame to edit it in.  This frame is deleted when you send the message.

   All the Rmail commands to send a message use the mail-composition
method that you have chosen (*note Mail Methods::).


File: emacs,  Node: Rmail Summary,  Next: Rmail Sorting,  Prev: Rmail Reply,  Up: Rmail

33.11 Summaries
===============

A "summary" is a buffer containing one line per message to give you an
overview of the mail in an Rmail file.  Each line shows the message
number and date, the sender, the line count, the labels, and the
subject.  Moving point in the summary buffer selects messages as you
move to their summary lines.  Almost all Rmail commands are valid in
the summary buffer also; when used there, they apply to the message
described by the current line of the summary.

   A summary buffer applies to a single Rmail file only; if you are
editing multiple Rmail files, each one can have its own summary buffer.
The summary buffer name is made by appending `-summary' to the Rmail
buffer's name.  Normally only one summary buffer is displayed at a time.

* Menu:

* Rmail Make Summary::       Making various sorts of summaries.
* Rmail Summary Edit::       Manipulating messages from the summary.


File: emacs,  Node: Rmail Make Summary,  Next: Rmail Summary Edit,  Up: Rmail Summary

33.11.1 Making Summaries
------------------------

Here are the commands to create a summary for the current Rmail buffer.
Once the Rmail buffer has a summary, changes in the Rmail buffer (such
as deleting or expunging messages, and getting new mail) automatically
update the summary.

`h'
`C-M-h'
     Summarize all messages (`rmail-summary').

`l LABELS <RET>'
`C-M-l LABELS <RET>'
     Summarize messages that have one or more of the specified labels
     (`rmail-summary-by-labels').

`C-M-r RCPTS <RET>'
     Summarize messages that match the specified recipients
     (`rmail-summary-by-recipients').

`C-M-t TOPIC <RET>'
     Summarize messages that have a match for the specified regexp
     TOPIC in their subjects (`rmail-summary-by-topic').

`C-M-s REGEXP <RET>'
     Summarize messages whose headers match the specified regular
     expression REGEXP (`rmail-summary-by-regexp').

`C-M-f SENDERS <RET>'
     Summarize messages that match the specified senders.
     (`rmail-summary-by-senders').

   The `h' or `C-M-h' (`rmail-summary') command fills the summary buffer
for the current Rmail buffer with a summary of all the messages in the
buffer.  It then displays and selects the summary buffer in another
window.

   `C-M-l LABELS <RET>' (`rmail-summary-by-labels') makes a partial
summary mentioning only the messages that have one or more of the
labels LABELS.  LABELS should contain label names separated by commas.

   `C-M-r RCPTS <RET>' (`rmail-summary-by-recipients') makes a partial
summary mentioning only the messages that have one or more recipients
matching the regular expression RCPTS.  You can use commas to separate
multiple regular expressions.  These are matched against the `To',
`From', and `CC' headers (supply a prefix argument to exclude this
header).

   `C-M-t TOPIC <RET>' (`rmail-summary-by-topic') makes a partial
summary mentioning only the messages whose subjects have a match for
the regular expression TOPIC.  You can use commas to separate multiple
regular expressions.  With a prefix argument, the match is against the
whole message, not just the subject.

   `C-M-s REGEXP <RET>' (`rmail-summary-by-regexp') makes a partial
summary that mentions only the messages whose headers (including the
date and the subject lines) match the regular expression REGEXP.

   `C-M-f SENDERS <RET>' (`rmail-summary-by-senders') makes a partial
summary that mentions only the messages whose `From' fields match the
regular expression SENDERS.  You can use commas to separate multiple
regular expressions.

   Note that there is only one summary buffer for any Rmail buffer;
making any kind of summary discards any previous summary.

   The variable `rmail-summary-window-size' says how many lines to use
for the summary window.  The variable `rmail-summary-line-count-flag'
controls whether the summary line for a message should include the line
count of the message.  Setting this option to nil might speed up the
generation of summaries.


File: emacs,  Node: Rmail Summary Edit,  Prev: Rmail Make Summary,  Up: Rmail Summary

33.11.2 Editing in Summaries
----------------------------

You can use the Rmail summary buffer to do almost anything you can do
in the Rmail buffer itself.  In fact, once you have a summary buffer,
there's no need to switch back to the Rmail buffer.

   You can select and display various messages in the Rmail buffer, from
the summary buffer, just by moving point in the summary buffer to
different lines.  It doesn't matter what Emacs command you use to move
point; whichever line point is on at the end of the command, that
message is selected in the Rmail buffer.

   Almost all Rmail commands work in the summary buffer as well as in
the Rmail buffer.  Thus, `d' in the summary buffer deletes the current
message, `u' undeletes, and `x' expunges.  (However, in the summary
buffer, a numeric argument to `d', `C-d' and `u' serves as a repeat
count.  A negative argument reverses the meaning of `d' and `C-d'.
Also, if there are no more undeleted messages in the relevant
direction, the delete commands go to the first or last message, rather
than staying on the current message.)  `o' and `C-o' output the current
message to a FILE; `r' starts a reply to it; etc.  You can scroll the
current message while remaining in the summary buffer using <SPC> and
<DEL>.

   `M-u' (`rmail-summary-undelete-many') undeletes all deleted messages
in the summary.  A prefix argument means to undelete that many of the
previous deleted messages.

   The Rmail commands to move between messages also work in the summary
buffer, but with a twist: they move through the set of messages included
in the summary.  They also ensure the Rmail buffer appears on the screen
(unlike cursor motion commands, which update the contents of the Rmail
buffer but don't display it in a window unless it already appears).
Here is a list of these commands:

`n'
     Move to next line, skipping lines saying `deleted', and select its
     message (`rmail-summary-next-msg').

`p'
     Move to previous line, skipping lines saying `deleted', and select
     its message (`rmail-summary-previous-msg').

`M-n'
     Move to next line and select its message
     (`rmail-summary-next-all').

`M-p'
     Move to previous line and select its message
     (`rmail-summary-previous-all').

`>'
     Move to the last line, and select its message
     (`rmail-summary-last-message').

`<'
     Move to the first line, and select its message
     (`rmail-summary-first-message').

`j'
`<RET>'
     Select the message on the current line (ensuring that the Rmail
     buffer appears on the screen; `rmail-summary-goto-msg').  With
     argument N, select message number N and move to its line in the
     summary buffer; this signals an error if the message is not listed
     in the summary buffer.

`M-s PATTERN <RET>'
     Search through messages for PATTERN starting with the current
     message; select the message found, and move point in the summary
     buffer to that message's line (`rmail-summary-search').  A prefix
     argument acts as a repeat count; a negative argument means search
     backward (equivalent to `rmail-summary-search-backward'.)

`C-M-n LABELS <RET>'
     Move to the next message with at least one of the specified labels
     (`rmail-summary-next-labeled-message').  LABELS is a
     comma-separated list of labels.  A prefix argument acts as a repeat
     count.

`C-M-p LABELS <RET>'
     Move to the previous message with at least one of the specified
     labels (`rmail-summary-previous-labeled-message').

`C-c C-n <RET>'
     Move to the next message with the same subject as the current
     message (`rmail-summary-next-same-subject').  A prefix argument
     acts as a repeat count.

`C-c C-p <RET>'
     Move to the previous message with the same subject as the current
     message (`rmail-summary-previous-same-subject').

   Deletion, undeletion, and getting new mail, and even selection of a
different message all update the summary buffer when you do them in the
Rmail buffer.  If the variable `rmail-redisplay-summary' is non-`nil',
these actions also bring the summary buffer back onto the screen.

   When you are finished using the summary, type `Q'
(`rmail-summary-wipe') to delete the summary buffer's window.  You can
also exit Rmail while in the summary: `q' (`rmail-summary-quit')
deletes the summary window, then exits from Rmail by saving the Rmail
file and switching to another buffer.  Alternatively, `b'
(`rmail-summary-bury') simply buries the Rmail summary and buffer.


File: emacs,  Node: Rmail Sorting,  Next: Rmail Display,  Prev: Rmail Summary,  Up: Rmail

33.12 Sorting the Rmail File
============================

`C-c C-s C-d'
`M-x rmail-sort-by-date'
     Sort messages of current Rmail buffer by date.

`C-c C-s C-s'
`M-x rmail-sort-by-subject'
     Sort messages of current Rmail buffer by subject.

`C-c C-s C-a'
`M-x rmail-sort-by-author'
     Sort messages of current Rmail buffer by author's name.

`C-c C-s C-r'
`M-x rmail-sort-by-recipient'
     Sort messages of current Rmail buffer by recipient's names.

`C-c C-s C-c'
`M-x rmail-sort-by-correspondent'
     Sort messages of current Rmail buffer by the name of the other
     correspondent.

`C-c C-s C-l'
`M-x rmail-sort-by-lines'
     Sort messages of current Rmail buffer by number of lines.

`C-c C-s C-k <RET> LABELS <RET>'
`M-x rmail-sort-by-labels <RET> LABELS <RET>'
     Sort messages of current Rmail buffer by labels.  The argument
     LABELS should be a comma-separated list of labels.  The order of
     these labels specifies the order of messages; messages with the
     first label come first, messages with the second label come
     second, and so on.  Messages that have none of these labels come
     last.

   The Rmail sort commands perform a _stable sort_: if there is no
reason to prefer either one of two messages, their order remains
unchanged.  You can use this to sort by more than one criterion.  For
example, if you use `rmail-sort-by-date' and then
`rmail-sort-by-author', messages from the same author appear in order
by date.

   With a prefix argument, all these commands reverse the order of
comparison.  This means they sort messages from newest to oldest, from
biggest to smallest, or in reverse alphabetical order.

   The same keys in the summary buffer run similar functions; for
example, `C-c C-s C-l' runs `rmail-summary-sort-by-lines'.  Note that
these commands always sort the whole Rmail buffer, even if the summary
is only showing a subset of messages.

   Note that you cannot undo a sort, so you may wish to save the Rmail
buffer before sorting it.


File: emacs,  Node: Rmail Display,  Next: Rmail Coding,  Prev: Rmail Sorting,  Up: Rmail

33.13 Display of Messages
=========================

This section describes how Rmail displays mail headers, MIME sections
and attachments, URLs, and encrypted messages.

`t'
     Toggle display of complete header (`rmail-toggle-header').

   Before displaying each message for the first time, Rmail reformats
its header, hiding uninteresting header fields to reduce clutter.  The
`t' (`rmail-toggle-header') command toggles this, switching between
showing the reformatted header fields and showing the complete,
original header.  With a positive prefix argument, the command shows
the reformatted header; with a zero or negative prefix argument, it
shows the full header.  Selecting the message again also reformats it
if necessary.

   The variable `rmail-ignored-headers' holds a regular expression
specifying the header fields to hide; any matching header line will be
hidden.  The variable `rmail-nonignored-headers' overrides this: any
header field matching that regular expression is shown even if it
matches `rmail-ignored-headers' too.  The variable
`rmail-displayed-headers' is an alternative to these two variables; if
non-`nil', this should be a regular expression specifying which headers
to display (the default is `nil').

   Rmail highlights certain header fields that are especially
interesting--by default, the `From' and `Subject' fields.  This
highlighting uses the `rmail-highlight' face.  The variable
`rmail-highlighted-headers' holds a regular expression specifying the
header fields to highlight; if it matches the beginning of a header
field, that whole field is highlighted.  To disable this feature, set
`rmail-highlighted-headers' to `nil'.

   If a message is in MIME (Multipurpose Internet Mail Extensions)
format and contains multiple parts (MIME entities), Rmail displays each
part with a "tagline".  The tagline summarizes the part's index, size,
and content type.  Depending on the content type, it may also contain
one or more buttons; these perform actions such as saving the part into
a file.

`<RET>'
     Hide or show the MIME part at point (`rmail-mime-toggle-hidden').

`<TAB>'
     Move point to the next MIME tagline button.
     (`rmail-mime-next-item').

`S-<TAB>'
     Move point to the previous MIME part (`rmail-mime-previous-item').

`v'
     Toggle between MIME display and raw message (`rmail-mime').

   Each plain-text MIME part is initially displayed immediately after
its tagline, as part of the Rmail buffer, while MIME parts of other
types are represented only by their taglines, with their actual
contents hidden.  In either case, you can toggle a MIME part between
its "displayed" and "hidden" states by typing <RET> anywhere in the
part--or anywhere in its tagline (except for buttons for other actions,
if there are any).  Type <RET> (or click with the mouse) to activate a
tagline button, and <TAB> to cycle point between tagline buttons.

   The `v' (`rmail-mime') command toggles between the default MIME
display described above, and a "raw" display showing the undecoded MIME
data.  With a prefix argument, this command toggles the display of only
an entity at point.

   To prevent Rmail from handling MIME decoded messages, change the
variable `rmail-enable-mime' to `nil'.  When this is the case, the `v'
(`rmail-mime') command instead creates a temporary buffer to display
the current MIME message.

   If the current message is an encrypted one, use the command `M-x
rmail-epa-decrypt' to decrypt it, using the EasyPG library (*note
EasyPG: (epa)Top.).

   You can highlight and activate URLs in the Rmail buffer using Goto
Address mode:

     (add-hook 'rmail-show-message-hook 'goto-address-mode)

Then you can browse these URLs by clicking on them with `Mouse-2' (or
`Mouse-1' quickly) or by moving to one and typing `C-c <RET>'.  *Note
Activating URLs: Goto Address mode.


File: emacs,  Node: Rmail Coding,  Next: Rmail Editing,  Prev: Rmail Display,  Up: Rmail

33.14 Rmail and Coding Systems
==============================

Rmail automatically decodes messages which contain non-ASCII
characters, just as Emacs does with files you visit and with subprocess
output.  Rmail uses the standard `charset=CHARSET' header in the
message, if any, to determine how the message was encoded by the
sender.  It maps CHARSET into the corresponding Emacs coding system
(*note Coding Systems::), and uses that coding system to decode message
text.  If the message header doesn't have the `charset' specification,
or if CHARSET is not recognized, Rmail chooses the coding system with
the usual Emacs heuristics and defaults (*note Recognize Coding::).

   Occasionally, a message is decoded incorrectly, either because Emacs
guessed the wrong coding system in the absence of the `charset'
specification, or because the specification was inaccurate.  For
example, a misconfigured mailer could send a message with a
`charset=iso-8859-1' header when the message is actually encoded in
`koi8-r'.  When you see the message text garbled, or some of its
characters displayed as hex codes or empty boxes, this may have
happened.

   You can correct the problem by decoding the message again using the
right coding system, if you can figure out or guess which one is right.
To do this, invoke the `M-x rmail-redecode-body' command.  It reads the
name of a coding system, and then redecodes the message using the
coding system you specified.  If you specified the right coding system,
the result should be readable.


File: emacs,  Node: Rmail Editing,  Next: Rmail Digest,  Prev: Rmail Coding,  Up: Rmail

33.15 Editing Within a Message
==============================

Most of the usual Emacs key bindings are available in Rmail mode,
though a few, such as `C-M-n' and `C-M-h', are redefined by Rmail for
other purposes.  However, the Rmail buffer is normally read only, and
most of the letters are redefined as Rmail commands.  If you want to
edit the text of a message, you must use the Rmail command `e'.

`e'
     Edit the current message as ordinary text.

   The `e' command (`rmail-edit-current-message') switches from Rmail
mode into Rmail Edit mode, another major mode which is nearly the same
as Text mode.  The mode line indicates this change.

   In Rmail Edit mode, letters insert themselves as usual and the Rmail
commands are not available.  You can edit the message body and header
fields.  When you are finished editing the message, type `C-c C-c' to
switch back to Rmail mode.  Alternatively, you can return to Rmail mode
but cancel any editing that you have done, by typing `C-c C-]'.

   Entering Rmail Edit mode runs the hook `text-mode-hook'; then it
runs the hook `rmail-edit-mode-hook' (*note Hooks::).  Returning to
ordinary Rmail mode adds the attribute `edited' to the message, if you
have made any changes in it.


File: emacs,  Node: Rmail Digest,  Next: Rmail Rot13,  Prev: Rmail Editing,  Up: Rmail

33.16 Digest Messages
=====================

A "digest message" is a message which exists to contain and carry
several other messages.  Digests are used on some mailing lists; all
the messages that arrive for the list during a period of time such as
one day are put inside a single digest which is then sent to the
subscribers.  Transmitting the single digest uses less computer time
than transmitting the individual messages even though the total size is
the same, because of the per-message overhead in network mail
transmission.

   When you receive a digest message, the most convenient way to read
it is to "undigestify" it: to turn it back into many individual
messages.  Then you can read and delete the individual messages as it
suits you.  To do this, select the digest message and type the command
`M-x undigestify-rmail-message'.  This extracts the submessages as
separate Rmail messages, and inserts them following the digest.  The
digest message itself is flagged as deleted.


File: emacs,  Node: Rmail Rot13,  Next: Movemail,  Prev: Rmail Digest,  Up: Rmail

33.17 Reading Rot13 Messages
============================

Mailing list messages that might offend or annoy some readers are
sometimes encoded in a simple code called "rot13"--so named because it
rotates the alphabet by 13 letters.  This code is not for secrecy, as it
provides none; rather, it enables those who wish to to avoid seeing the
real text of the message.  For example, a review of a film might use
rot13 to hide important plot points.

   To view a buffer that uses the rot13 code, use the command `M-x
rot13-other-window'.  This displays the current buffer in another window
which applies the code when displaying the text.


File: emacs,  Node: Movemail,  Next: Remote Mailboxes,  Prev: Rmail Rot13,  Up: Rmail

33.18 `movemail' program
========================

Rmail uses the `movemail' program to move mail from your inbox to your
Rmail file (*note Rmail Inbox::).  When loaded for the first time,
Rmail attempts to locate the `movemail' program and determine its
version.  There are two versions of the `movemail' program: the native
one, shipped with GNU Emacs (the "emacs version") and the one included
in GNU mailutils (the "mailutils version", *note movemail:
(mailutils)movemail.).  They support the same command line syntax and
the same basic subset of options.  However, the Mailutils version
offers additional features.

   The Emacs version of `movemail' is able to retrieve mail from the
usual Unix mailbox formats and from remote mailboxes using the POP3
protocol.

   The Mailutils version is able to handle a wide set of mailbox
formats, such as plain Unix mailboxes, `maildir' and `MH' mailboxes,
etc.  It is able to access remote mailboxes using the POP3 or IMAP4
protocol, and can retrieve mail from them using a TLS encrypted
channel.  It also accepts mailbox arguments in URL form.  The detailed
description of mailbox URLs can be found in *note URL: (mailutils)URL.
In short, a URL is:

     PROTO://[USER[:PASSWORD]@]HOST-OR-FILE-NAME

where square brackets denote optional elements.

PROTO
     Specifies the "mailbox protocol", or "format" to use.  The exact
     semantics of the rest of URL elements depends on the actual value
     of PROTO (see below).

USER
     User name to access the remote mailbox.

PASSWORD
     User password to access the remote mailbox.

HOST-OR-FILE-NAME
     Hostname of the remote server for remote mailboxes or file name of
     a local mailbox.

PROTO can be one of:

`mbox'
     Usual Unix mailbox format.  In this case, neither USER nor PASS
     are used, and HOST-OR-FILE-NAME denotes the file name of the
     mailbox file, e.g., `mbox://var/spool/mail/smith'.

`mh'
     A local mailbox in the MH format.  USER and PASS are not used.
     HOST-OR-FILE-NAME denotes the name of MH folder, e.g.,
     `mh://Mail/inbox'.

`maildir'
     A local mailbox in the maildir format.  USER and PASS are not
     used, and HOST-OR-FILE-NAME denotes the name of `maildir' mailbox,
     e.g., `maildir://mail/inbox'.

`file'
     Any local mailbox format.  Its actual format is detected
     automatically by `movemail'.

`pop'
     A remote mailbox to be accessed via POP3 protocol.  USER specifies
     the remote user name to use, PASS may be used to specify the user
     password, HOST-OR-FILE-NAME is the name or IP address of the
     remote mail server to connect to; e.g.,
     `pop://smith:guessme@remote.server.net'.

`imap'
     A remote mailbox to be accessed via IMAP4 protocol.  USER
     specifies the remote user name to use, PASS may be used to specify
     the user password, HOST-OR-FILE-NAME is the name or IP address of
     the remote mail server to connect to; e.g.,
     `imap://smith:guessme@remote.server.net'.

   Alternatively, you can specify the file name of the mailbox to use.
This is equivalent to specifying the `file' protocol:

     /var/spool/mail/USER == file://var/spool/mail/USER

   The variable `rmail-movemail-program' controls which version of
`movemail' to use.  If that is a string, it specifies the absolute file
name of the `movemail' executable.  If it is `nil', Rmail searches for
`movemail' in the directories listed in `rmail-movemail-search-path',
then in `exec-path' (*note Shell::), then in `exec-directory'.


File: emacs,  Node: Remote Mailboxes,  Next: Other Mailbox Formats,  Prev: Movemail,  Up: Rmail

33.19 Retrieving Mail from Remote Mailboxes
===========================================

Some sites use a method called POP for accessing users' inbox data
instead of storing the data in inbox files.  By default, the `Emacs
movemail' can work with POP (unless the Emacs `configure' script was
run with the option `--without-pop').

   Similarly, the Mailutils `movemail' by default supports POP, unless
it was configured with the `--disable-pop' option.

   Both versions of `movemail' only work with POP3, not with older
versions of POP.

   No matter which flavor of `movemail' you use, you can specify a POP
inbox by using a POP "URL" (*note Movemail::).  A POP URL is a "file
name" of the form `pop://USERNAME@HOSTNAME', where HOSTNAME is the host
name or IP address of the remote mail server and USERNAME is the user
name on that server.  Additionally, you may specify the password in the
mailbox URL: `pop://USERNAME:PASSWORD@HOSTNAME'.  In this case,
PASSWORD takes preference over the one set by `rmail-remote-password'
(see below).  This is especially useful if you have several remote
mailboxes with different passwords.

   For backward compatibility, Rmail also supports an alternative way of
specifying remote POP mailboxes.  Specifying an inbox name in the form
`po:USERNAME:HOSTNAME' is equivalent to `pop://USERNAME@HOSTNAME'.  If
you omit the :HOSTNAME part, the `MAILHOST' environment variable
specifies the machine on which to look for the POP server.

   Another method for accessing remote mailboxes is IMAP.  This method
is supported only by the Mailutils `movemail'.  To specify an IMAP
mailbox in the inbox list, use the following mailbox URL:
`imap://USERNAME[:PASSWORD]@HOSTNAME'.  The PASSWORD part is optional,
as described above.

   Accessing a remote mailbox may require a password.  Rmail uses the
following algorithm to retrieve it:

  1. If a PASSWORD is present in the mailbox URL (see above), it is
     used.

  2. If the variable `rmail-remote-password-required' is `nil', Rmail
     assumes no password is required.

  3. If the variable `rmail-remote-password' is non-`nil', its value is
     used.

  4. Otherwise, Rmail will ask you for the password to use.

   If you need to pass additional command-line flags to `movemail', set
the variable `rmail-movemail-flags' a list of the flags you wish to
use.  Do not use this variable to pass the `-p' flag to preserve your
inbox contents; use `rmail-preserve-inbox' instead.

   The `movemail' program installed at your site may support Kerberos
authentication (the Emacs `movemail' does so if Emacs was configured
with the option `--with-kerberos' or `--with-kerberos5').  If it is
supported, it is used by default whenever you attempt to retrieve POP
mail when `rmail-remote-password' and `rmail-remote-password-required'
are unset.

   Some POP servers store messages in reverse order.  If your server
does this, and you would rather read your mail in the order in which it
was received, you can tell `movemail' to reverse the order of
downloaded messages by adding the `-r' flag to `rmail-movemail-flags'.

   Mailutils `movemail' supports TLS encryption.  If you wish to use
it, add the `--tls' flag to `rmail-movemail-flags'.


File: emacs,  Node: Other Mailbox Formats,  Prev: Remote Mailboxes,  Up: Rmail

33.20 Retrieving Mail from Local Mailboxes in Various Formats
=============================================================

If your incoming mail is stored on a local machine in a format other
than Unix mailbox, you will need the Mailutils `movemail' to retrieve
it.  *Note Movemail::, for the detailed description of `movemail'
versions.  For example, to access mail from a inbox in `maildir' format
located in `/var/spool/mail/in', you would include the following in the
Rmail inbox list:

     maildir://var/spool/mail/in


File: emacs,  Node: Gnus,  Next: Document View,  Prev: Rmail,  Up: Top

34 Gnus
*******

Gnus is an Emacs package primarily designed for reading and posting
Usenet news.  It can also be used to read and respond to messages from
a number of other sources--email, remote directories, digests, and so
on.  Here we introduce Gnus and describe several basic features.  For
full details, see *note Gnus: (gnus)Top.

* Menu:

* Buffers of Gnus::     The group, summary, and article buffers.
* Gnus Startup::        What you should know about starting Gnus.
* Gnus Group Buffer::   A short description of Gnus group commands.
* Gnus Summary Buffer:: A short description of Gnus summary commands.


File: emacs,  Node: Buffers of Gnus,  Next: Gnus Startup,  Up: Gnus

34.1 Gnus Buffers
=================

Gnus uses several buffers to display information and to receive
commands.  The three most commonly-used Gnus buffers are the "group
buffer", the "summary buffer" and the "article buffer".

   The "group buffer" contains a list of article sources (e.g.
newsgroups and email inboxes), which are collectively referred to as
"groups".  This is the first buffer Gnus displays when it starts up.
It normally displays only the groups to which you subscribe and that
contain unread articles.  From this buffer, you can select a group to
read.

   The "summary buffer" lists the articles in a single group, showing
one article per line.  By default, it displays each article's author,
subject, and line number, but this is customizable; *Note Summary
Buffer Format: (gnus)Summary Buffer Format.  The summary buffer is
created when you select a group in the group buffer, and is killed when
you exit the group.

   From the summary buffer, you can choose an article to view.  The
article is displayed in the "article buffer".  In normal Gnus usage,
you view this buffer but do not select it--all useful Gnus commands can
be invoked from the summary buffer.  But you can select the article
buffer, and execute Gnus commands from it, if you wish.


File: emacs,  Node: Gnus Startup,  Next: Gnus Group Buffer,  Prev: Buffers of Gnus,  Up: Gnus

34.2 When Gnus Starts Up
========================

If your system has been set up for reading Usenet news, getting started
with Gnus is easy--just type `M-x gnus'.

   On starting up, Gnus reads your "news initialization file": a file
named `.newsrc' in your home directory which lists your Usenet
newsgroups and subscriptions (this file is not unique to Gnus; it is
used by many other newsreader programs).  It then tries to contact the
system's default news server, which is typically specified by the
`NNTPSERVER' environment variable.

   If your system does not have a default news server, or if you wish
to use Gnus for reading email, then before invoking `M-x gnus' you need
to tell Gnus where to get news and/or mail.  To do this, customize the
variables `gnus-select-method' and/or `gnus-secondary-select-methods'.
*Note Finding the News: (gnus)Finding the News.

   Once Gnus has started up, it displays the group buffer.  By default,
the group buffer shows only a small number of "subscribed groups".
Groups with other statuses--"unsubscribed", "killed", or "zombie"--are
hidden.  The first time you start Gnus, any group to which you are not
subscribed is made into a killed group; any group that subsequently
appears on the news server becomes a zombie group.

   To proceed, you must select a group in the group buffer to open the
summary buffer for that group; then, select an article in the summary
buffer to view its article buffer in a separate window.  The following
sections explain how to use the group and summary buffers to do this.

   To quit Gnus, type `q' in the group buffer.  This automatically
records your group statuses in the files `.newsrc' and `.newsrc.eld',
so that they take effect in subsequent Gnus sessions.


File: emacs,  Node: Gnus Group Buffer,  Next: Gnus Summary Buffer,  Prev: Gnus Startup,  Up: Gnus

34.3 Using the Gnus Group Buffer
================================

The following commands are available in the Gnus group buffer:

`<SPC>'
     Switch to the summary buffer for the group on the current line.

`l'
`A s'
     In the group buffer, list only the groups to which you subscribe
     and which contain unread articles (this is the default listing).

`L'
`A u'
     List all subscribed and unsubscribed groups, but not killed or
     zombie groups.

`A k'
     List killed groups.

`A z'
     List zombie groups.

`u'
     Toggle the subscription status of the group on the current line
     (i.e. turn a subscribed group into an unsubscribed group, or vice
     versa).  Invoking this on a killed or zombie group turns it into an
     unsubscribed group.

`C-k'
     Kill the group on the current line.  Killed groups are not
     recorded in the `.newsrc' file, and they are not shown in the `l'
     or `L' listings.

`<DEL>'
     Move point to the previous group containing unread articles.

`n'
     Move point to the next unread group.

`p'
     Move point to the previous unread group.

`q'
     Update your Gnus settings, and quit Gnus.


File: emacs,  Node: Gnus Summary Buffer,  Prev: Gnus Group Buffer,  Up: Gnus

34.4 Using the Gnus Summary Buffer
==================================

The following commands are available in the Gnus summary buffer:

`<SPC>'
     If there is no article selected, select the article on the current
     line and display its article buffer.  Otherwise, try scrolling the
     selected article buffer in its window; on reaching the end of the
     buffer, select the next unread article.

     Thus, you can read through all articles by repeatedly typing <SPC>.

`<DEL>'
     Scroll the text of the article backwards.

`n'
     Select the next unread article.

`p'
     Select the previous unread article.

`s'
     Do an incremental search on the selected article buffer, as if you
     switched to the buffer and typed `C-s' (*note Incremental
     Search::).

`M-s REGEXP <RET>'
     Search forward for articles containing a match for REGEXP.

`q'
     Exit the summary buffer and return to the group buffer.


File: emacs,  Node: Document View,  Next: Shell,  Prev: Gnus,  Up: Top

35 Document Viewing
*******************

DocView mode is a major mode for viewing DVI, PostScript (PS), PDF,
OpenDocument, and Microsoft Office documents.  It provides features
such as slicing, zooming, and searching inside documents.  It works by
converting the document to a set of images using the `gs' (GhostScript)
command and other external tools (1), and displaying those images.

   When you visit a document file that can be displayed with DocView
mode, Emacs automatically uses DocView mode (2).  As an exception, when
you visit a PostScript file, Emacs switches to PS mode, a major mode
for editing PostScript files as text; however, it also enables DocView
minor mode, so you can type `C-c C-c' to view the document with
DocView.  In either DocView mode or DocView minor mode, repeating `C-c
C-c' (`doc-view-toggle-display') toggles between DocView and the
underlying file contents.

   You can explicitly enable DocView mode with the command `M-x
doc-view-mode'.  You can toggle DocView minor mode with `M-x
doc-view-minor-mode'.

   When DocView mode starts, it displays a welcome screen and begins
formatting the file, page by page.  It displays the first page once
that has been formatted.

   To kill the DocView buffer, type `k'
(`doc-view-kill-proc-and-buffer').  To bury it, type `q'
(`quit-window').

* Menu:

* Navigation: DocView Navigation.  Navigating DocView buffers.
* Searching: DocView Searching.    Searching inside documents.
* Slicing: DocView Slicing.        Specifying which part of a page is displayed.
* Conversion: DocView Conversion.  Influencing and triggering conversion.

   ---------- Footnotes ----------

   (1) `gs' is a hard requirement.  For DVI files, `dvipdf' or
`dvipdfm' is needed.  For OpenDocument and Microsoft Office documents,
the `unoconv' tool is needed.

   (2) The needed external tools for the document type must be
available, and Emacs must be running in a graphical frame and have PNG
image support.  If any of these requirements is not fulfilled, Emacs
falls back to another major mode.


File: emacs,  Node: DocView Navigation,  Next: DocView Searching,  Up: Document View

35.1 DocView Navigation
=======================

In DocView mode, you can scroll the current page using the usual Emacs
movement keys: `C-p', `C-n', `C-b', `C-f', and the arrow keys.

   By default, the line-motion keys `C-p' and `C-n' stop scrolling at
the beginning and end of the current page, respectively.  However, if
you change the variable `doc-view-continuous' to a non-`nil' value,
then `C-p' displays the previous page if you are already at the
beginning of the current page, and `C-n' displays the next page if you
are at the end of the current page.

   You can also display the next page by typing `n', <next> or `C-x ]'
(`doc-view-next-page').  To display the previous page, type `p',
<prior> or `C-x [' (`doc-view-previous-page').

   <SPC> (`doc-view-scroll-up-or-next-page') is a convenient way to
advance through the document.  It scrolls within the current page or
advances to the next.  <DEL> moves backwards in a similar way
(`doc-view-scroll-down-or-previous-page').

   To go to the first page, type `M-<' (`doc-view-first-page'); to go
to the last one, type `M->' (`doc-view-last-page').  To jump to a page
by its number, type `M-g M-g' or `M-g g' (`doc-view-goto-page').

   You can enlarge or shrink the document with `+' (`doc-view-enlarge')
and `-' (`doc-view-shrink').  These commands work by reconverting the
document at the new size.  To specify the default size for DocView,
customize the variable `doc-view-resolution'.


File: emacs,  Node: DocView Searching,  Next: DocView Slicing,  Prev: DocView Navigation,  Up: Document View

35.2 DocView Searching
======================

In DocView mode, you can search the file's text for a regular
expression (*note Regexps::).  The interface for searching is inspired
by `isearch' (*note Incremental Search::).

   To begin a search, type `C-s' (`doc-view-search') or `C-r'
(`doc-view-search-backward').  This reads a regular expression using a
minibuffer, then echoes the number of matches found within the
document.  You can move forward and back among the matches by typing
`C-s' and `C-r'.  DocView mode has no way to show the match inside the
page image; instead, it displays a tooltip (at the mouse position)
listing all matching lines in the current page.  To force display of
this tooltip, type `C-t' (`doc-view-show-tooltip').

   To start a new search, use the search command with a prefix
argument; i.e., `C-u C-s' for a forward search or `C-u C-r' for a
backward search.


File: emacs,  Node: DocView Slicing,  Next: DocView Conversion,  Prev: DocView Searching,  Up: Document View

35.3 DocView Slicing
====================

Documents often have wide margins for printing.  They are annoying when
reading the document on the screen, because they use up screen space
and can cause inconvenient scrolling.

   With DocView you can hide these margins by selecting a "slice" of
pages to display.  A slice is a rectangle within the page area; once
you specify a slice in DocView, it applies to whichever page you look
at.

   To specify the slice numerically, type `s s' (`doc-view-set-slice');
then enter the top left pixel position and the slice's width and height.

   A more convenient graphical way to specify the slice is with `s m'
(`doc-view-set-slice-using-mouse'), where you use the mouse to select
the slice.

   To cancel the selected slice, type `s r' (`doc-view-reset-slice').
Then DocView shows the entire page including its entire margins.


File: emacs,  Node: DocView Conversion,  Prev: DocView Slicing,  Up: Document View

35.4 DocView Conversion
=======================

For efficiency, DocView caches the images produced by `gs'.  The name
of this directory is given by the variable `doc-view-cache-directory'.
You can clear the cache directory by typing `M-x doc-view-clear-cache'.

   To force reconversion of the currently viewed document, type `r' or
`g' (`revert-buffer').  To kill the converter process associated with
the current buffer, type `K' (`doc-view-kill-proc').  The command `k'
(`doc-view-kill-proc-and-buffer') kills the converter process and the
DocView buffer.


File: emacs,  Node: Shell,  Next: Emacs Server,  Prev: Document View,  Up: Top

36 Running Shell Commands from Emacs
************************************

Emacs has commands for passing single command lines to shell
subprocesses, and for running a shell interactively with input and
output to an Emacs buffer, and for running a shell in a terminal
emulator window.

`M-! CMD <RET>'
     Run the shell command CMD and display the output (`shell-command').

`M-| CMD <RET>'
     Run the shell command CMD with region contents as input;
     optionally replace the region with the output
     (`shell-command-on-region').

`M-& CMD <RET>'
     Run the shell command CMD asynchronously, and display the output
     (`async-shell-command').

`M-x shell'
     Run a subshell with input and output through an Emacs buffer.  You
     can then give commands interactively.

`M-x term'
     Run a subshell with input and output through an Emacs buffer.  You
     can then give commands interactively.  Full terminal emulation is
     available.

   Whenever you specify a relative file name for an executable program
(either in the CMD argument to one of the above commands, or in other
contexts), Emacs searches for the program in the directories specified
by the variable `exec-path'.  The value of this variable must be a list
of directory names; the default value is initialized from the
environment variable `PATH' when Emacs is started (*note General
Variables::).

   `M-x eshell' invokes a shell implemented entirely in Emacs.  It is
documented in its own manual.  *Note Eshell: (eshell)Top.

* Menu:

* Single Shell::           How to run one shell command and return.
* Interactive Shell::      Permanent shell taking input via Emacs.
* Shell Mode::             Special Emacs commands used with permanent shell.
* Shell Prompts::          Two ways to recognize shell prompts.
* History: Shell History.  Repeating previous commands in a shell buffer.
* Directory Tracking::     Keeping track when the subshell changes directory.
* Options: Shell Options.  Options for customizing Shell mode.
* Terminal emulator::      An Emacs window as a terminal emulator.
* Term Mode::              Special Emacs commands used in Term mode.
* Remote Host::            Connecting to another computer.
* Serial Terminal::        Connecting to a serial port.


File: emacs,  Node: Single Shell,  Next: Interactive Shell,  Up: Shell

36.1 Single Shell Commands
==========================

`M-!' (`shell-command') reads a line of text using the minibuffer and
executes it as a shell command, in a subshell made just for that
command.  Standard input for the command comes from the null device.
If the shell command produces any output, the output appears either in
the echo area (if it is short), or in an Emacs buffer named `*Shell
Command Output*', displayed in another window (if the output is long).

   For instance, one way to decompress a file named `foo.gz' is to type
`M-! gunzip foo.gz <RET>'.  That shell command normally creates the
file `foo' and produces no terminal output.

   A numeric argument to `shell-command', e.g. `M-1 M-!', causes it to
insert terminal output into the current buffer instead of a separate
buffer.  It puts point before the output, and sets the mark after the
output.  For instance, `M-1 M-! gunzip < foo.gz <RET>' would insert the
uncompressed form of the file `foo.gz' into the current buffer.

   Provided the specified shell command does not end with `&', it runs
"synchronously", and you must wait for it to exit before continuing to
use Emacs.  To stop waiting, type `C-g' to quit; this sends a `SIGINT'
signal to terminate the shell command (this is the same signal that
`C-c' normally generates in the shell).  Emacs then waits until the
command actually terminates.  If the shell command doesn't stop
(because it ignores the `SIGINT' signal), type `C-g' again; this sends
the command a `SIGKILL' signal, which is impossible to ignore.

   A shell command that ends in `&' is executed "asynchronously", and
you can continue to use Emacs as it runs.  You can also type `M-&'
(`async-shell-command') to execute a shell command asynchronously; this
is exactly like calling `M-!' with a trailing `&', except that you do
not need the `&'.  The output buffer for asynchronous shell commands is
named `*Async Shell Command*'.  Emacs inserts the output into this
buffer as it comes in, whether or not the buffer is visible in a window.

   `M-|' (`shell-command-on-region') is like `M-!', but passes the
contents of the region as the standard input to the shell command,
instead of no input.  With a numeric argument, it deletes the old
region and replaces it with the output from the shell command.

   For example, you can use `M-|' with the `gpg' program to see what
keys are in the buffer.  If the buffer contains a GnuPG key, type `C-x
h M-| gpg <RET>' to feed the entire buffer contents to `gpg'.  This
will output the list of keys to the `*Shell Command Output*' buffer.

   The above commands use the shell specified by the variable
`shell-file-name'.  Its default value is determined by the `SHELL'
environment variable when Emacs is started.  If the file name is
relative, Emacs searches the directories listed in `exec-path' (*note
Shell::).

   To specify a coding system for `M-!' or `M-|', use the command `C-x
<RET> c' immediately beforehand.  *Note Communication Coding::.

   By default, error output is intermixed with the regular output in
the output buffer.  But if you change the value of the variable
`shell-command-default-error-buffer' to a string, error output is
inserted into a buffer of that name.


File: emacs,  Node: Interactive Shell,  Next: Shell Mode,  Prev: Single Shell,  Up: Shell

36.2 Interactive Subshell
=========================

To run a subshell interactively, type `M-x shell'.  This creates (or
reuses) a buffer named `*shell*', and runs a shell subprocess with
input coming from and output going to that buffer.  That is to say, any
terminal output from the subshell goes into the buffer, advancing
point, and any terminal input for the subshell comes from text in the
buffer.  To give input to the subshell, go to the end of the buffer and
type the input, terminated by <RET>.

   While the subshell is waiting or running a command, you can switch
windows or buffers and perform other editing in Emacs.  Emacs inserts
the output from the subshell into the Shell buffer whenever it has time
to process it (e.g. while waiting for keyboard input).

   In the Shell buffer, prompts are displayed with the face
`comint-highlight-prompt', and submitted input lines are displayed with
the face `comint-highlight-input'.  This makes it easier to distinguish
input lines from the shell output.  *Note Faces::.

   To make multiple subshells, invoke `M-x shell' with a prefix
argument (e.g. `C-u M-x shell').  Then the command will read a buffer
name, and create (or reuse) a subshell in that buffer.  You can also
rename the `*shell*' buffer using `M-x rename-uniquely', then create a
new `*shell*' buffer using plain `M-x shell'.  Subshells in different
buffers run independently and in parallel.

   To specify the shell file name used by `M-x shell', customize the
variable `explicit-shell-file-name'.  If this is `nil' (the default),
Emacs uses the environment variable `ESHELL' if it exists.  Otherwise,
it usually uses the variable `shell-file-name' (*note Single Shell::);
but if the default directory is remote (*note Remote Files::), it
prompts you for the shell file name.

   Emacs sends the new shell the contents of the file
`~/.emacs_SHELLNAME' as input, if it exists, where SHELLNAME is the
name of the file that the shell was loaded from.  For example, if you
use bash, the file sent to it is `~/.emacs_bash'.  If this file is not
found, Emacs tries with `~/.emacs.d/init_SHELLNAME.sh'.

   To specify a coding system for the shell, you can use the command
`C-x <RET> c' immediately before `M-x shell'.  You can also change the
coding system for a running subshell by typing `C-x <RET> p' in the
shell buffer.  *Note Communication Coding::.

   Emacs sets the environment variable `INSIDE_EMACS' in the subshell
to `VERSION,comint', where VERSION is the Emacs version (e.g. `24.1').
Programs can check this variable to determine whether they are running
inside an Emacs subshell.  (It also sets the `EMACS' environment
variable to `t', if that environment variable is not already defined.
However, this environment variable is deprecated; programs that use it
should switch to using `INSIDE_EMACS' instead.)


File: emacs,  Node: Shell Mode,  Next: Shell Prompts,  Prev: Interactive Shell,  Up: Shell

36.3 Shell Mode
===============

The major mode for Shell buffers is Shell mode.  Many of its special
commands are bound to the `C-c' prefix, and resemble the usual editing
and job control characters present in ordinary shells, except that you
must type `C-c' first.  Here is a list of Shell mode commands:

`<RET>'
     Send the current line as input to the subshell
     (`comint-send-input').  Any shell prompt at the beginning of the
     line is omitted (*note Shell Prompts::).  If point is at the end of
     buffer, this is like submitting the command line in an ordinary
     interactive shell.  However, you can also invoke <RET> elsewhere
     in the shell buffer to submit the current line as input.

`<TAB>'
     Complete the command name or file name before point in the shell
     buffer (`completion-at-point').  This uses the usual Emacs
     completion rules (*note Completion::), with the completion
     alternatives being file names, environment variable names, the
     shell command history, and history references (*note History
     References::).

     The variable `shell-completion-fignore' specifies a list of file
     name extensions to ignore in Shell mode completion.  The default
     setting is `nil', but some users prefer `("~" "#" "%")' to ignore
     file names ending in `~', `#' or `%'.  Other related Comint modes
     use the variable `comint-completion-fignore' instead.

`M-?'
     Display temporarily a list of the possible completions of the file
     name before point (`comint-dynamic-list-filename-completions').

`C-d'
     Either delete a character or send EOF
     (`comint-delchar-or-maybe-eof').  Typed at the end of the shell
     buffer, this sends EOF to the subshell.  Typed at any other
     position in the buffer, this deletes a character as usual.

`C-c C-a'
     Move to the beginning of the line, but after the prompt if any
     (`comint-bol-or-process-mark').  If you repeat this command twice
     in a row, the second time it moves back to the process mark, which
     is the beginning of the input that you have not yet sent to the
     subshell.  (Normally that is the same place--the end of the prompt
     on this line--but after `C-c <SPC>' the process mark may be in a
     previous line.)

`C-c <SPC>'
     Accumulate multiple lines of input, then send them together.  This
     command inserts a newline before point, but does not send the
     preceding text as input to the subshell--at least, not yet.  Both
     lines, the one before this newline and the one after, will be sent
     together (along with the newline that separates them), when you
     type <RET>.

`C-c C-u'
     Kill all text pending at end of buffer to be sent as input
     (`comint-kill-input').  If point is not at end of buffer, this
     only kills the part of this text that precedes point.

`C-c C-w'
     Kill a word before point (`backward-kill-word').

`C-c C-c'
     Interrupt the shell or its current subjob if any
     (`comint-interrupt-subjob').  This command also kills any shell
     input pending in the shell buffer and not yet sent.

`C-c C-z'
     Stop the shell or its current subjob if any (`comint-stop-subjob').
     This command also kills any shell input pending in the shell
     buffer and not yet sent.

`C-c C-\'
     Send quit signal to the shell or its current subjob if any
     (`comint-quit-subjob').  This command also kills any shell input
     pending in the shell buffer and not yet sent.

`C-c C-o'
     Delete the last batch of output from a shell command
     (`comint-delete-output').  This is useful if a shell command spews
     out lots of output that just gets in the way.

`C-c C-s'
     Write the last batch of output from a shell command to a file
     (`comint-write-output').  With a prefix argument, the file is
     appended to instead.  Any prompt at the end of the output is not
     written.

`C-c C-r'
`C-M-l'
     Scroll to display the beginning of the last batch of output at the
     top of the window; also move the cursor there
     (`comint-show-output').

`C-c C-e'
     Scroll to put the end of the buffer at the bottom of the window
     (`comint-show-maximum-output').

`C-c C-f'
     Move forward across one shell command, but not beyond the current
     line (`shell-forward-command').  The variable
     `shell-command-regexp' specifies how to recognize the end of a
     command.

`C-c C-b'
     Move backward across one shell command, but not beyond the current
     line (`shell-backward-command').

`M-x dirs'
     Ask the shell for its working directory, and update the Shell
     buffer's default directory.  *Note Directory Tracking::.

`M-x send-invisible <RET> TEXT <RET>'
     Send TEXT as input to the shell, after reading it without echoing.
     This is useful when a shell command runs a program that asks for a
     password.

     Please note that Emacs will not echo passwords by default.  If you
     really want them to be echoed, evaluate the following Lisp
     expression:

          (remove-hook 'comint-output-filter-functions
                       'comint-watch-for-password-prompt)

`M-x comint-continue-subjob'
     Continue the shell process.  This is useful if you accidentally
     suspend the shell process.(1)

`M-x comint-strip-ctrl-m'
     Discard all control-M characters from the current group of shell
     output.  The most convenient way to use this command is to make it
     run automatically when you get output from the subshell.  To do
     that, evaluate this Lisp expression:

          (add-hook 'comint-output-filter-functions
                    'comint-strip-ctrl-m)

`M-x comint-truncate-buffer'
     This command truncates the shell buffer to a certain maximum
     number of lines, specified by the variable
     `comint-buffer-maximum-size'.  Here's how to do this automatically
     each time you get output from the subshell:

          (add-hook 'comint-output-filter-functions
                    'comint-truncate-buffer)

   Shell mode is a derivative of Comint mode, a general-purpose mode for
communicating with interactive subprocesses.  Most of the features of
Shell mode actually come from Comint mode, as you can see from the
command names listed above.  The special features of Shell mode include
the directory tracking feature, and a few user commands.

   Other Emacs features that use variants of Comint mode include GUD
(*note Debuggers::) and `M-x run-lisp' (*note External Lisp::).

   You can use `M-x comint-run' to execute any program of your choice
in a subprocess using unmodified Comint mode--without the
specializations of Shell mode.

   ---------- Footnotes ----------

   (1) You should not suspend the shell process.  Suspending a subjob
of the shell is a completely different matter--that is normal practice,
but you must use the shell to continue the subjob; this command won't
do it.


File: emacs,  Node: Shell Prompts,  Next: Shell History,  Prev: Shell Mode,  Up: Shell

36.4 Shell Prompts
==================

A prompt is text output by a program to show that it is ready to accept
new user input.  Normally, Comint mode (and thus Shell mode)
automatically figures out part of the buffer is a prompt, based on the
output of the subprocess.  (Specifically, it assumes that any received
output line which doesn't end with a newline is a prompt.)

   Comint mode divides the buffer into two types of "fields": input
fields (where user input is typed) and output fields (everywhere else).
Prompts are part of the output fields.  Most Emacs motion commands do
not cross field boundaries, unless they move over multiple lines.  For
instance, when point is in the input field on a shell command line,
`C-a' puts point at the beginning of the input field, after the prompt.
Internally, the fields are implemented using the `field' text property
(*note Text Properties: (elisp)Text Properties.).

   If you change the variable `comint-use-prompt-regexp' to a non-`nil'
value, then Comint mode recognize prompts using a regular expression
(*note Regexps::).  In Shell mode, the regular expression is specified
by the variable `shell-prompt-pattern'.  The default value of
`comint-use-prompt-regexp' is `nil', because this method for
recognizing prompts is unreliable, but you may want to set it to a
non-`nil' value in unusual circumstances.  In that case, Emacs does not
divide the Comint buffer into fields, so the general motion commands
behave as they normally do in buffers without special text properties.
However, you can use the paragraph motion commands to conveniently
navigate the buffer (*note Paragraphs::); in Shell mode, Emacs uses
`shell-prompt-pattern' as paragraph boundaries.


File: emacs,  Node: Shell History,  Next: Directory Tracking,  Prev: Shell Prompts,  Up: Shell

36.5 Shell Command History
==========================

Shell buffers support three ways of repeating earlier commands.  You
can use keys like those used for the minibuffer history; these work
much as they do in the minibuffer, inserting text from prior commands
while point remains always at the end of the buffer.  You can move
through the buffer to previous inputs in their original place, then
resubmit them or copy them to the end.  Or you can use a `!'-style
history reference.

* Menu:

* Ring: Shell Ring.             Fetching commands from the history list.
* Copy: Shell History Copying.  Moving to a command and then copying it.
* History References::          Expanding `!'-style history references.


File: emacs,  Node: Shell Ring,  Next: Shell History Copying,  Up: Shell History

36.5.1 Shell History Ring
-------------------------

`M-p'
`C-<UP>'
     Fetch the next earlier old shell command.

`M-n'
`C-<DOWN>'
     Fetch the next later old shell command.

`M-r'
     Begin an incremental regexp search of old shell commands.

`C-c C-x'
     Fetch the next subsequent command from the history.

`C-c .'
     Fetch one argument from an old shell command.

`C-c C-l'
     Display the buffer's history of shell commands in another window
     (`comint-dynamic-list-input-ring').

   Shell buffers provide a history of previously entered shell
commands.  To reuse shell commands from the history, use the editing
commands `M-p', `M-n', `M-r' and `M-s'.  These work just like the
minibuffer history commands (*note Minibuffer History::), except that
they operate within the Shell buffer rather than the minibuffer.

   `M-p' fetches an earlier shell command to the end of the shell
buffer.  Successive use of `M-p' fetches successively earlier shell
commands, each replacing any text that was already present as potential
shell input.  `M-n' does likewise except that it finds successively
more recent shell commands from the buffer.  `C-<UP>' works like `M-p',
and `C-<DOWN>' like `M-n'.

   The history search command `M-r' begins an incremental regular
expression search of previous shell commands.  After typing `M-r',
start typing the desired string or regular expression; the last
matching shell command will be displayed in the current line.
Incremental search commands have their usual effects--for instance,
`C-s' and `C-r' search forward and backward for the next match (*note
Incremental Search::).  When you find the desired input, type <RET> to
terminate the search.  This puts the input in the command line.  Any
partial input you were composing before navigating the history list is
restored when you go to the beginning or end of the history ring.

   Often it is useful to reexecute several successive shell commands
that were previously executed in sequence.  To do this, first find and
reexecute the first command of the sequence.  Then type `C-c C-x'; that
will fetch the following command--the one that follows the command you
just repeated.  Then type <RET> to reexecute this command.  You can
reexecute several successive commands by typing `C-c C-x <RET>' over
and over.

   The command `C-c .' (`comint-input-previous-argument') copies an
individual argument from a previous command, like `ESC .' in Bash.  The
simplest use copies the last argument from the previous shell command.
With a prefix argument N, it copies the Nth argument instead.
Repeating `C-c .' copies from an earlier shell command instead, always
using the same value of N (don't give a prefix argument when you repeat
the `C-c .' command).

   These commands get the text of previous shell commands from a special
history list, not from the shell buffer itself.  Thus, editing the shell
buffer, or even killing large parts of it, does not affect the history
that these commands access.

   Some shells store their command histories in files so that you can
refer to commands from previous shell sessions.  Emacs reads the
command history file for your chosen shell, to initialize its own
command history.  The file name is `~/.bash_history' for bash,
`~/.sh_history' for ksh, and `~/.history' for other shells.


File: emacs,  Node: Shell History Copying,  Next: History References,  Prev: Shell Ring,  Up: Shell History

36.5.2 Shell History Copying
----------------------------

`C-c C-p'
     Move point to the previous prompt (`comint-previous-prompt').

`C-c C-n'
     Move point to the following prompt (`comint-next-prompt').

`C-c <RET>'
     Copy the input command at point, inserting the copy at the end of
     the buffer (`comint-copy-old-input').  This is useful if you move
     point back to a previous command.  After you copy the command, you
     can submit the copy as input with <RET>.  If you wish, you can edit
     the copy before resubmitting it.  If you use this command on an
     output line, it copies that line to the end of the buffer.

`Mouse-2'
     If `comint-use-prompt-regexp' is `nil' (the default), copy the old
     input command that you click on, inserting the copy at the end of
     the buffer (`comint-insert-input').  If `comint-use-prompt-regexp'
     is non-`nil', or if the click is not over old input, just yank as
     usual.

   Moving to a previous input and then copying it with `C-c <RET>' or
`Mouse-2' produces the same results--the same buffer contents--that you
would get by using `M-p' enough times to fetch that previous input from
the history list.  However, `C-c <RET>' copies the text from the
buffer, which can be different from what is in the history list if you
edit the input text in the buffer after it has been sent.


File: emacs,  Node: History References,  Prev: Shell History Copying,  Up: Shell History

36.5.3 Shell History References
-------------------------------

Various shells including csh and bash support "history references" that
begin with `!' and `^'.  Shell mode recognizes these constructs, and
can perform the history substitution for you.

   If you insert a history reference and type <TAB>, this searches the
input history for a matching command, performs substitution if
necessary, and places the result in the buffer in place of the history
reference.  For example, you can fetch the most recent command
beginning with `mv' with `! m v <TAB>'.  You can edit the command if
you wish, and then resubmit the command to the shell by typing <RET>.

   Shell mode can optionally expand history references in the buffer
when you send them to the shell.  To request this, set the variable
`comint-input-autoexpand' to `input'.  You can make <SPC> perform
history expansion by binding <SPC> to the command `comint-magic-space'.

   Shell mode recognizes history references when they follow a prompt.
*Note Shell Prompts::, for how Shell mode recognizes prompts.


File: emacs,  Node: Directory Tracking,  Next: Shell Options,  Prev: Shell History,  Up: Shell

36.6 Directory Tracking
=======================

Shell mode keeps track of `cd', `pushd' and `popd' commands given to
the subshell, in order to keep the Shell buffer's default directory
(*note File Names::) the same as the shell's working directory.  It
recognizes these commands by examining lines of input that you send.

   If you use aliases for these commands, you can tell Emacs to
recognize them also, by setting the variables `shell-pushd-regexp',
`shell-popd-regexp', and `shell-cd-regexp' to the appropriate regular
expressions (*note Regexps::).  For example, if `shell-pushd-regexp'
matches the beginning of a shell command line, that line is regarded as
a `pushd' command.  These commands are recognized only at the beginning
of a shell command line.

   If Emacs gets confused about changes in the working directory of the
subshell, type `M-x dirs'.  This command asks the shell for its working
directory and updates the default directory accordingly.  It works for
shells that support the most common command syntax, but may not work
for unusual shells.

   You can also use Dirtrack mode, a buffer-local minor mode that
implements an alternative method of tracking the shell's working
directory.  To use this method, your shell prompt must contain the
working directory at all times, and you must supply a regular
expression for recognizing which part of the prompt contains the
working directory; see the documentation of the variable
`dirtrack-list' for details.  To use Dirtrack mode, type `M-x
dirtrack-mode' in the Shell buffer, or add `dirtrack-mode' to
`shell-mode-hook' (*note Hooks::).


File: emacs,  Node: Shell Options,  Next: Terminal emulator,  Prev: Directory Tracking,  Up: Shell

36.7 Shell Mode Options
=======================

If the variable `comint-scroll-to-bottom-on-input' is non-`nil',
insertion and yank commands scroll the selected window to the bottom
before inserting.  The default is `nil'.

   If `comint-scroll-show-maximum-output' is non-`nil', then arrival of
output when point is at the end tries to scroll the last line of text
to the bottom line of the window, showing as much useful text as
possible.  (This mimics the scrolling behavior of most terminals.)  The
default is `t'.

   By setting `comint-move-point-for-output', you can opt for having
point jump to the end of the buffer whenever output arrives--no matter
where in the buffer point was before.  If the value is `this', point
jumps in the selected window.  If the value is `all', point jumps in
each window that shows the Comint buffer.  If the value is `other',
point jumps in all nonselected windows that show the current buffer.
The default value is `nil', which means point does not jump to the end.

   If you set `comint-prompt-read-only', the prompts in the Comint
buffer are read-only.

   The variable `comint-input-ignoredups' controls whether successive
identical inputs are stored in the input history.  A non-`nil' value
means to omit an input that is the same as the previous input.  The
default is `nil', which means to store each input even if it is equal
to the previous input.

   Three variables customize file name completion.  The variable
`comint-completion-addsuffix' controls whether completion inserts a
space or a slash to indicate a fully completed file or directory name
(non-`nil' means do insert a space or slash).
`comint-completion-recexact', if non-`nil', directs <TAB> to choose the
shortest possible completion if the usual Emacs completion algorithm
cannot add even a single character.  `comint-completion-autolist', if
non-`nil', says to list all the possible completions whenever
completion is not exact.

   Command completion normally considers only executable files.  If you
set `shell-completion-execonly' to `nil', it considers nonexecutable
files as well.

   You can configure the behavior of `pushd'.  Variables control
whether `pushd' behaves like `cd' if no argument is given
(`shell-pushd-tohome'), pop rather than rotate with a numeric argument
(`shell-pushd-dextract'), and only add directories to the directory
stack if they are not already on it (`shell-pushd-dunique').  The
values you choose should match the underlying shell, of course.


File: emacs,  Node: Terminal emulator,  Next: Term Mode,  Prev: Shell Options,  Up: Shell

36.8 Emacs Terminal Emulator
============================

To run a subshell in a terminal emulator, use `M-x term'.  This creates
(or reuses) a buffer named `*terminal*', and runs a subshell with input
coming from your keyboard, and output going to that buffer.

   The terminal emulator uses Term mode, which has two input modes.  In
line mode, Term basically acts like Shell mode (*note Shell Mode::).

   In char mode, each character is sent directly to the subshell, as
"terminal input".  Any "echoing" of your input is the responsibility of
the subshell.  The sole exception is the terminal escape character,
which by default is `C-c' (*note Term Mode::).  Any "terminal output"
from the subshell goes into the buffer, advancing point.

   Some programs (such as Emacs itself) need to control the appearance
on the terminal screen in detail.  They do this by sending special
control codes.  The exact control codes needed vary from terminal to
terminal, but nowadays most terminals and terminal emulators (including
`xterm') understand the ANSI-standard (VT100-style) escape sequences.
Term mode recognizes these escape sequences, and handles each one
appropriately, changing the buffer so that the appearance of the window
matches what it would be on a real terminal.  You can actually run
Emacs inside an Emacs Term window.

   You can also Term mode to communicate with a device connected to a
serial port.  *Note Serial Terminal::.

   The file name used to load the subshell is determined the same way
as for Shell mode.  To make multiple terminal emulators, rename the
buffer `*terminal*' to something different using `M-x rename-uniquely',
just as with Shell mode.

   Unlike Shell mode, Term mode does not track the current directory by
examining your input.  But some shells can tell Term what the current
directory is.  This is done automatically by `bash' version 1.15 and
later.


File: emacs,  Node: Term Mode,  Next: Remote Host,  Prev: Terminal emulator,  Up: Shell

36.9 Term Mode
==============

The terminal emulator uses Term mode, which has two input modes.  In
line mode, Term basically acts like Shell mode (*note Shell Mode::).
In char mode, each character is sent directly to the subshell, except
for the Term escape character, normally `C-c'.

   To switch between line and char mode, use these commands:

`C-c C-j'
     Switch to line mode (`term-line-mode').  Do nothing if already in
     line mode.

`C-c C-k'
     Switch to char mode (`term-char-mode').  Do nothing if already in
     char mode.

   The following commands are only available in char mode:

`C-c C-c'
     Send a literal <C-c> to the sub-shell.

`C-c CHAR'
     This is equivalent to `C-x CHAR' in normal Emacs.  For example,
     `C-c o' invokes the global binding of `C-x o', which is normally
     `other-window'.

   Term mode has a page-at-a-time feature.  When enabled, it makes
output pause at the end of each screenful:

`C-c C-q'
     Toggle the page-at-a-time feature.  This command works in both line
     and char modes.  When the feature is enabled, the mode-line
     displays the word `page', and each time Term receives more than a
     screenful of output, it pauses and displays `**MORE**' in the
     mode-line.  Type <SPC> to display the next screenful of output, or
     `?' to see your other options.  The interface is similar to the
     `more' program.


File: emacs,  Node: Remote Host,  Next: Serial Terminal,  Prev: Term Mode,  Up: Shell

36.10 Remote Host Shell
=======================

You can login to a remote computer, using whatever commands you would
from a regular terminal (e.g. using the `telnet' or `rlogin' commands),
from a Term window.

   A program that asks you for a password will normally suppress
echoing of the password, so the password will not show up in the
buffer.  This will happen just as if you were using a real terminal, if
the buffer is in char mode.  If it is in line mode, the password is
temporarily visible, but will be erased when you hit return.  (This
happens automatically; there is no special password processing.)

   When you log in to a different machine, you need to specify the type
of terminal you're using, by setting the `TERM' environment variable in
the environment for the remote login command.  (If you use bash, you do
that by writing the variable assignment before the remote login
command, without a separating comma.)  Terminal types `ansi' or `vt100'
will work on most systems.


File: emacs,  Node: Serial Terminal,  Prev: Remote Host,  Up: Shell

36.11 Serial Terminal
=====================

If you have a device connected to a serial port of your computer, you
can communicate with it by typing `M-x serial-term'.  This command asks
for a serial port name and speed, and switches to a new Term mode
buffer.  Emacs communicates with the serial device through this buffer
just like it does with a terminal in ordinary Term mode.

   The speed of the serial port is measured in bits per second.  The
most common speed is 9600 bits per second.  You can change the speed
interactively by clicking on the mode line.

   A serial port can be configured even more by clicking on "8N1" in
the mode line.  By default, a serial port is configured as "8N1", which
means that each byte consists of 8 data bits, No parity check bit, and
1 stopbit.

   If the speed or the configuration is wrong, you cannot communicate
with your device and will probably only see garbage output in the
window.


File: emacs,  Node: Emacs Server,  Next: Printing,  Prev: Shell,  Up: Top

37 Using Emacs as a Server
**************************

Various programs can invoke your choice of editor to edit a particular
piece of text.  For instance, version control programs invoke an editor
to enter version control logs (*note Version Control::), and the Unix
`mail' utility invokes an editor to enter a message to send.  By
convention, your choice of editor is specified by the environment
variable `EDITOR'.  If you set `EDITOR' to `emacs', Emacs would be
invoked, but in an inconvenient way--by starting a new Emacs process.
This is inconvenient because the new Emacs process doesn't share
buffers, a command history, or other kinds of information with any
existing Emacs process.

   You can solve this problem by setting up Emacs as an "edit server",
so that it "listens" for external edit requests and acts accordingly.
There are two ways to start an Emacs server:

   * Run the command `server-start' in an existing Emacs process:
     either type `M-x server-start', or put the expression
     `(server-start)' in your init file (*note Init File::).  The
     existing Emacs process is the server; when you exit Emacs, the
     server dies with the Emacs process.

   * Run Emacs as a "daemon", using the `--daemon' command-line option.
     *Note Initial Options::.  When Emacs is started this way, it calls
     `server-start' after initialization, and returns control to the
     calling terminal instead of opening an initial frame; it then
     waits in the background, listening for edit requests.

   Either way, once an Emacs server is started, you can use a shell
command called `emacsclient' to connect to the Emacs process and tell
it to visit a file.  You can then set the `EDITOR' environment variable
to `emacsclient', so that external programs will use the existing Emacs
process for editing.(1)

   You can run multiple Emacs servers on the same machine by giving
each one a unique "server name", using the variable `server-name'.  For
example, `M-x set-variable <RET> server-name <RET> foo <RET>' sets the
server name to `foo'.  The `emacsclient' program can specify a server by
name, using the `-s' option (*note emacsclient Options::).

   If you have defined a server by a unique server name, it is possible
to connect to the server from another Emacs instance and evaluate Lisp
expressions on the server, using the `server-eval-at' function.  For
instance, `(server-eval-at "foo" '(+ 1 2))' evaluates the expression
`(+ 1 2)' on the `foo' server, and returns `3'.  (If there is no server
with that name, an error is signaled.)  Currently, this feature is
mainly useful for developers.

* Menu:

* Invoking emacsclient:: Connecting to the Emacs server.
* emacsclient Options::  Emacs client startup options.

   ---------- Footnotes ----------

   (1) Some programs use a different environment variable; for example,
to make TeX use `emacsclient', set the `TEXEDIT' environment variable
to `emacsclient +%d %s'.


File: emacs,  Node: Invoking emacsclient,  Next: emacsclient Options,  Up: Emacs Server

37.1 Invoking `emacsclient'
===========================

The simplest way to use the `emacsclient' program is to run the shell
command `emacsclient FILE', where FILE is a file name.  This connects
to an Emacs server, and tells that Emacs process to visit FILE in one
of its existing frames--either a graphical frame, or one in a text
terminal (*note Frames::).  You can then select that frame to begin
editing.

   If there is no Emacs server, the `emacsclient' program halts with an
error message.  If the Emacs process has no existing frame--which can
happen if it was started as a daemon (*note Emacs Server::)--then Emacs
opens a frame on the terminal in which you called `emacsclient'.

   You can also force `emacsclient' to open a new frame on a graphical
display, or on a text terminal, using the `-c' and `-t' options.  *Note
emacsclient Options::.

   If you are running on a single text terminal, you can switch between
`emacsclient''s shell and the Emacs server using one of two methods:
(i) run the Emacs server and `emacsclient' on different virtual
terminals, and switch to the Emacs server's virtual terminal after
calling `emacsclient'; or (ii) call `emacsclient' from within the Emacs
server itself, using Shell mode (*note Interactive Shell::) or Term
mode (*note Term Mode::); `emacsclient' blocks only the subshell under
Emacs, and you can still use Emacs to edit the file.

   When you finish editing FILE in the Emacs server, type `C-x #'
(`server-edit') in its buffer.  This saves the file and sends a message
back to the `emacsclient' program, telling it to exit.  Programs that
use `EDITOR' usually wait for the "editor"--in this case
`emacsclient'--to exit before doing something else.

   You can also call `emacsclient' with multiple file name arguments:
`emacsclient FILE1 FILE2 ...' tells the Emacs server to visit FILE1,
FILE2, and so forth.  Emacs selects the buffer visiting FILE1, and
buries the other buffers at the bottom of the buffer list (*note
Buffers::).  The `emacsclient' program exits once all the specified
files are finished (i.e., once you have typed `C-x #' in each server
buffer).

   Finishing with a server buffer also kills the buffer, unless it
already existed in the Emacs session before the server was asked to
create it.  However, if you set `server-kill-new-buffers' to `nil',
then a different criterion is used: finishing with a server buffer
kills it if the file name matches the regular expression
`server-temp-file-regexp'.  This is set up to distinguish certain
"temporary" files.

   Each `C-x #' checks for other pending external requests to edit
various files, and selects the next such file.  You can switch to a
server buffer manually if you wish; you don't have to arrive at it with
`C-x #'.  But `C-x #' is the way to tell `emacsclient' that you are
finished.

   If you set the value of the variable `server-window' to a window or
a frame, `C-x #' always displays the next server buffer in that window
or in that frame.


File: emacs,  Node: emacsclient Options,  Prev: Invoking emacsclient,  Up: Emacs Server

37.2 `emacsclient' Options
==========================

You can pass some optional arguments to the `emacsclient' program, such
as:

     emacsclient -c +12 FILE1 +4:3 FILE2

The `+LINE' or `+LINE:COLUMN' arguments specify line numbers, or line
and column numbers, for the next file argument.  These behave like the
command line arguments for Emacs itself.  *Note Action Arguments::.

   The other optional arguments recognized by `emacsclient' are listed
below:

`-a COMMAND'
`--alternate-editor=COMMAND'
     Specify a command to run if `emacsclient' fails to contact Emacs.
     This is useful when running `emacsclient' in a script.

     As a special exception, if COMMAND is the empty string, then
     `emacsclient' starts Emacs in daemon mode (as `emacs --daemon')
     and then tries connecting again.

     The environment variable `ALTERNATE_EDITOR' has the same effect as
     the `-a' option.  If both are present, the latter takes precedence.

`-c'
     Create a new graphical "client frame", instead of using an
     existing Emacs frame.  If you omit a filename argument while
     supplying the `-c' option, the new frame displays the `*scratch*'
     buffer (*note Buffers::).  See below for the special behavior of
     `C-x C-c' in a client frame.

     If Emacs is unable to create a new graphical frame (e.g. if it is
     unable to connect to the X server), it tries to create a text
     terminal client frame, as though you had supplied the `-t' option
     instead (see below).

     On MS-Windows, a single Emacs session cannot display frames on both
     graphical and text terminals, nor on multiple text terminals.
     Thus, if the Emacs server is running on a text terminal, the `-c'
     option, like the `-t' option, creates a new frame in the server's
     current text terminal.  *Note Windows Startup::.

`-F ALIST'
`--frame-parameters=ALIST'
     Set the parameters for a newly-created graphical frame (*note
     Frame Parameters::).

`-d DISPLAY'
`--display=DISPLAY'
     Tell Emacs to open the given files on the X display DISPLAY
     (assuming there is more than one X display available).

`-e'
`--eval'
     Tell Emacs to evaluate some Emacs Lisp code, instead of visiting
     some files.  When this option is given, the arguments to
     `emacsclient' are interpreted as a list of expressions to
     evaluate, _not_ as a list of files to visit.

`-f SERVER-FILE'
`--server-file=SERVER-FILE'
     Specify a "server file" for connecting to an Emacs server via TCP.

     An Emacs server usually uses an operating system feature called a
     "local socket" to listen for connections.  Some operating systems,
     such as Microsoft Windows, do not support local sockets; in that
     case, Emacs uses TCP instead.  When you start the Emacs server,
     Emacs creates a server file containing some TCP information that
     `emacsclient' needs for making the connection.  By default, the
     server file is in `~/.emacs.d/server/'.  On Microsoft Windows, if
     `emacsclient' does not find the server file there, it looks in the
     `.emacs.d/server/' subdirectory of the directory pointed to by the
     `APPDATA' environment variable.  You can tell `emacsclient' to use
     a specific server file with the `-f' or `--server-file' option, or
     by setting the `EMACS_SERVER_FILE' environment variable.

     Even if local sockets are available, you can tell Emacs to use TCP
     by setting the variable `server-use-tcp' to `t'.  One advantage of
     TCP is that the server can accept connections from remote machines.
     For this to work, you must (i) set the variable `server-host' to
     the hostname or IP address of the machine on which the Emacs server
     runs, and (ii) provide `emacsclient' with the server file.  (One
     convenient way to do the latter is to put the server file on a
     networked file system such as NFS.)

     When the Emacs server is using TCP, the variable `server-port'
     determines the port number to listen on; the default value, `nil',
     means to choose a random port when the server starts.

`-n'
`--no-wait'
     Let `emacsclient' exit immediately, instead of waiting until all
     server buffers are finished.  You can take as long as you like to
     edit the server buffers within Emacs, and they are _not_ killed
     when you type `C-x #' in them.

`--parent-id ID'
     Open an `emacsclient' frame as a client frame in the parent X
     window with id ID, via the XEmbed protocol.  Currently, this
     option is mainly useful for developers.

`-q'
`--quiet'
     Do not let `emacsclient' display messages about waiting for Emacs
     or connecting to remote server sockets.

`-s SERVER-NAME'
`--socket-name=SERVER-NAME'
     Connect to the Emacs server named SERVER-NAME.  The server name is
     given by the variable `server-name' on the Emacs server.  If this
     option is omitted, `emacsclient' connects to the first server it
     finds.  (This option is not supported on MS-Windows.)

`-t'
`--tty'
`-nw'
     Create a new client frame on the current text terminal, instead of
     using an existing Emacs frame.  This is similar to the `-c'
     option, above, except that it creates a text terminal frame (*note
     Non-Window Terminals::).  If you omit a filename argument while
     supplying this option, the new frame displays the `*scratch*'
     buffer (*note Buffers::).  See below for the special behavior of
     `C-x C-c' in a client frame.

     On MS-Windows, a single Emacs session cannot display frames on both
     graphical and text terminals, nor on multiple text terminals.
     Thus, if the Emacs server is using the graphical display, `-t'
     behaves like `-c' (see above); whereas if the Emacs server is
     running on a text terminal, it creates a new frame in its current
     text terminal.  *Note Windows Startup::.

   The new graphical or text terminal frames created by the `-c' or
`-t' options are considered "client frames".  Any new frame that you
create from a client frame is also considered a client frame.  If you
type `C-x C-c' (`save-buffers-kill-terminal') in a client frame, that
command does not kill the Emacs session as it normally does (*note
Exiting::).  Instead, Emacs deletes the client frame; furthermore, if
the client frame has an `emacsclient' waiting to regain control (i.e.
if you did not supply the `-n' option), Emacs deletes all other frames
of the same client, and marks the client's server buffers as finished,
as though you had typed `C-x #' in all of them.  If it so happens that
there are no remaining frames after the client frame(s) are deleted,
the Emacs session exits.

   As an exception, when Emacs is started as a daemon, all frames are
considered client frames, and `C-x C-c' never kills Emacs.  To kill a
daemon session, type `M-x kill-emacs'.

   Note that the `-t' and `-n' options are contradictory: `-t' says to
take control of the current text terminal to create a new client frame,
while `-n' says not to take control of the text terminal.  If you
supply both options, Emacs visits the specified files(s) in an existing
frame rather than a new client frame, negating the effect of `-t'.


File: emacs,  Node: Printing,  Next: Sorting,  Prev: Emacs Server,  Up: Top

38 Printing Hard Copies
***********************

Emacs provides commands for printing hardcopies of either an entire
buffer or part of one.  You can invoke the printing commands directly,
as detailed below, or using the `File' menu on the menu bar.

   Aside from the commands described in this section, you can also
print hardcopies from Dired (*note Operating on Files::) and the diary
(*note Displaying the Diary::).  You can also "print" an Emacs buffer
to HTML with the command `M-x htmlfontify-buffer', which converts the
current buffer to a HTML file, replacing Emacs faces with CSS-based
markup.  Furthermore, Org mode allows you to "print" Org files to a
variety of formats, such as PDF (*note Org Mode::).

`M-x print-buffer'
     Print hardcopy of current buffer with page headings containing the
     file name and page number.

`M-x lpr-buffer'
     Print hardcopy of current buffer without page headings.

`M-x print-region'
     Like `print-buffer' but print only the current region.

`M-x lpr-region'
     Like `lpr-buffer' but print only the current region.

   On most operating system, the above hardcopy commands submit files
for printing by calling the `lpr' program.  To change the printer
program, customize the variable `lpr-command'.  To specify extra
switches to give the printer program, customize the list variable
`lpr-switches'.  Its value should be a list of option strings, each of
which should start with `-' (e.g. the option string `"-w80"' specifies
a line width of 80 columns).  The default is the empty list, `nil'.

   To specify the printer to use, set the variable `printer-name'.  The
default, `nil', specifies the default printer.  If you set it to a
printer name (a string), that name is passed to `lpr' with the `-P'
switch; if you are not using `lpr', you should specify the switch with
`lpr-printer-switch'.

   The variable `lpr-headers-switches' similarly specifies the extra
switches to use to make page headers.  The variable `lpr-add-switches'
controls whether to supply `-T' and `-J' options (suitable for `lpr')
to the printer program: `nil' means don't add them (this should be the
value if your printer program is not compatible with `lpr').

* Menu:

* PostScript::           Printing buffers or regions as PostScript.
* PostScript Variables:: Customizing the PostScript printing commands.
* Printing Package::     An optional advanced printing interface.


File: emacs,  Node: PostScript,  Next: PostScript Variables,  Up: Printing

38.1 PostScript Hardcopy
========================

These commands convert buffer contents to PostScript, either printing
it or leaving it in another Emacs buffer.

`M-x ps-print-buffer'
     Print hardcopy of the current buffer in PostScript form.

`M-x ps-print-region'
     Print hardcopy of the current region in PostScript form.

`M-x ps-print-buffer-with-faces'
     Print hardcopy of the current buffer in PostScript form, showing
     the faces used in the text by means of PostScript features.

`M-x ps-print-region-with-faces'
     Print hardcopy of the current region in PostScript form, showing
     the faces used in the text.

`M-x ps-spool-buffer'
     Generate and spool a PostScript image for the current buffer text.

`M-x ps-spool-region'
     Generate and spool a PostScript image for the current region.

`M-x ps-spool-buffer-with-faces'
     Generate and spool a PostScript image for the current buffer,
     showing the faces used.

`M-x ps-spool-region-with-faces'
     Generate and spool a PostScript image for the current region,
     showing the faces used.

`M-x ps-despool'
     Send the spooled PostScript to the printer.

`M-x handwrite'
     Generate/print PostScript for the current buffer as if handwritten.

   The `ps-print-buffer' and `ps-print-region' commands print buffer
contents in PostScript form.  One command prints the entire buffer; the
other, just the region.  The commands `ps-print-buffer-with-faces' and
`ps-print-region-with-faces' behave similarly, but use PostScript
features to show the faces (fonts and colors) of the buffer text.

   Interactively, when you use a prefix argument (`C-u'), the command
prompts the user for a file name, and saves the PostScript image in
that file instead of sending it to the printer.

   The commands whose names have `spool' instead of `print', generate
the PostScript output in an Emacs buffer instead of sending it to the
printer.

   Use the command `ps-despool' to send the spooled images to the
printer.  This command sends the PostScript generated by `-spool-'
commands (see commands above) to the printer.  With a prefix argument
(`C-u'), it prompts for a file name, and saves the spooled PostScript
image in that file instead of sending it to the printer.

   `M-x handwrite' is more frivolous.  It generates a PostScript
rendition of the current buffer as a cursive handwritten document.  It
can be customized in group `handwrite'.  This function only supports
ISO 8859-1 characters.


File: emacs,  Node: PostScript Variables,  Next: Printing Package,  Prev: PostScript,  Up: Printing

38.2 Variables for PostScript Hardcopy
======================================

All the PostScript hardcopy commands use the variables `ps-lpr-command'
and `ps-lpr-switches' to specify how to print the output.
`ps-lpr-command' specifies the command name to run, `ps-lpr-switches'
specifies command line options to use, and `ps-printer-name' specifies
the printer.  If you don't set the first two variables yourself, they
take their initial values from `lpr-command' and `lpr-switches'.  If
`ps-printer-name' is `nil', `printer-name' is used.

   The variable `ps-print-header' controls whether these commands add
header lines to each page--set it to `nil' to turn headers off.

   If your printer doesn't support colors, you should turn off color
processing by setting `ps-print-color-p' to `nil'.  By default, if the
display supports colors, Emacs produces hardcopy output with color
information; on black-and-white printers, colors are emulated with
shades of gray.  This might produce illegible output, even if your
screen colors only use shades of gray.

   Alternatively, you can set `ps-print-color-p' to `black-white' to
print colors on black/white printers.

   By default, PostScript printing ignores the background colors of the
faces, unless the variable `ps-use-face-background' is non-`nil'.  This
is to avoid unwanted interference with the zebra stripes and background
image/text.

   The variable `ps-paper-type' specifies which size of paper to format
for; legitimate values include `a4', `a3', `a4small', `b4', `b5',
`executive', `ledger', `legal', `letter', `letter-small', `statement',
`tabloid'.  The default is `letter'.  You can define additional paper
sizes by changing the variable `ps-page-dimensions-database'.

   The variable `ps-landscape-mode' specifies the orientation of
printing on the page.  The default is `nil', which stands for
"portrait" mode.  Any non-`nil' value specifies "landscape" mode.

   The variable `ps-number-of-columns' specifies the number of columns;
it takes effect in both landscape and portrait mode.  The default is 1.

   The variable `ps-font-family' specifies which font family to use for
printing ordinary text.  Legitimate values include `Courier',
`Helvetica', `NewCenturySchlbk', `Palatino' and `Times'.  The variable
`ps-font-size' specifies the size of the font for ordinary text.  It
defaults to 8.5 points.

   Emacs supports more scripts and characters than a typical PostScript
printer.  Thus, some of the characters in your buffer might not be
printable using the fonts built into your printer.  You can augment the
fonts supplied with the printer with those from the GNU Intlfonts
package, or you can instruct Emacs to use Intlfonts exclusively.  The
variable `ps-multibyte-buffer' controls this: the default value, `nil',
is appropriate for printing ASCII and Latin-1 characters; a value of
`non-latin-printer' is for printers which have the fonts for ASCII,
Latin-1, Japanese, and Korean characters built into them.  A value of
`bdf-font' arranges for the BDF fonts from the Intlfonts package to be
used for _all_ characters.  Finally, a value of `bdf-font-except-latin'
instructs the printer to use built-in fonts for ASCII and Latin-1
characters, and Intlfonts BDF fonts for the rest.

   To be able to use the BDF fonts, Emacs needs to know where to find
them.  The variable `bdf-directory-list' holds the list of directories
where Emacs should look for the fonts; the default value includes a
single directory `/usr/local/share/emacs/fonts/bdf'.

   Many other customization variables for these commands are defined and
described in the Lisp files `ps-print.el' and `ps-mule.el'.


File: emacs,  Node: Printing Package,  Prev: PostScript Variables,  Up: Printing

38.3 Printing Package
=====================

The basic Emacs facilities for printing hardcopy can be extended using
the Printing package.  This provides an easy-to-use interface for
choosing what to print, previewing PostScript files before printing,
and setting various printing options such as print headers, landscape
or portrait modes, duplex modes, and so forth.  On GNU/Linux or Unix
systems, the Printing package relies on the `gs' and `gv' utilities,
which are distributed as part of the GhostScript program.  On
MS-Windows, the `gstools' port of Ghostscript can be used.

   To use the Printing package, add `(require 'printing)' to your init
file (*note Init File::), followed by `(pr-update-menus)'.  This
function replaces the usual printing commands in the menu bar with a
`Printing' submenu that contains various printing options.  You can
also type `M-x pr-interface RET'; this creates a `*Printing Interface*'
buffer, similar to a customization buffer, where you can set the
printing options.  After selecting what and how to print, you start the
print job using the `Print' button (click `mouse-2' on it, or move
point over it and type `RET').  For further information on the various
options, use the `Interface Help' button.


File: emacs,  Node: Sorting,  Next: Picture Mode,  Prev: Printing,  Up: Top

39 Sorting Text
***************

Emacs provides several commands for sorting text in the buffer.  All
operate on the contents of the region.  They divide the text of the
region into many "sort records", identify a "sort key" for each record,
and then reorder the records into the order determined by the sort
keys.  The records are ordered so that their keys are in alphabetical
order, or, for numeric sorting, in numeric order.  In alphabetic
sorting, all upper-case letters `A' through `Z' come before lower-case
`a', in accord with the ASCII character sequence.

   The various sort commands differ in how they divide the text into
sort records and in which part of each record is used as the sort key.
Most of the commands make each line a separate sort record, but some
commands use paragraphs or pages as sort records.  Most of the sort
commands use each entire sort record as its own sort key, but some use
only a portion of the record as the sort key.

`M-x sort-lines'
     Divide the region into lines, and sort by comparing the entire
     text of a line.  A numeric argument means sort into descending
     order.

`M-x sort-paragraphs'
     Divide the region into paragraphs, and sort by comparing the entire
     text of a paragraph (except for leading blank lines).  A numeric
     argument means sort into descending order.

`M-x sort-pages'
     Divide the region into pages, and sort by comparing the entire
     text of a page (except for leading blank lines).  A numeric
     argument means sort into descending order.

`M-x sort-fields'
     Divide the region into lines, and sort by comparing the contents of
     one field in each line.  Fields are defined as separated by
     whitespace, so the first run of consecutive non-whitespace
     characters in a line constitutes field 1, the second such run
     constitutes field 2, etc.

     Specify which field to sort by with a numeric argument: 1 to sort
     by field 1, etc.  A negative argument means count fields from the
     right instead of from the left; thus, minus 1 means sort by the
     last field.  If several lines have identical contents in the field
     being sorted, they keep the same relative order that they had in
     the original buffer.

`M-x sort-numeric-fields'
     Like `M-x sort-fields' except the specified field is converted to
     an integer for each line, and the numbers are compared.  `10'
     comes before `2' when considered as text, but after it when
     considered as a number.  By default, numbers are interpreted
     according to `sort-numeric-base', but numbers beginning with `0x'
     or `0' are interpreted as hexadecimal and octal, respectively.

`M-x sort-columns'
     Like `M-x sort-fields' except that the text within each line used
     for comparison comes from a fixed range of columns.  See below for
     an explanation.

`M-x reverse-region'
     Reverse the order of the lines in the region.  This is useful for
     sorting into descending order by fields or columns, since those
     sort commands do not have a feature for doing that.

   For example, if the buffer contains this:

     On systems where clash detection (locking of files being edited) is
     implemented, Emacs also checks the first time you modify a buffer
     whether the file has changed on disk since it was last visited or
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.

applying `M-x sort-lines' to the entire buffer produces this:

     On systems where clash detection (locking of files being edited) is
     implemented, Emacs also checks the first time you modify a buffer
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.
     whether the file has changed on disk since it was last visited or

where the upper-case `O' sorts before all lower-case letters.  If you
use `C-u 2 M-x sort-fields' instead, you get this:

     implemented, Emacs also checks the first time you modify a buffer
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.
     On systems where clash detection (locking of files being edited) is
     whether the file has changed on disk since it was last visited or

where the sort keys were `Emacs', `If', `buffer', `systems' and `the'.

   `M-x sort-columns' requires more explanation.  You specify the
columns by putting point at one of the columns and the mark at the other
column.  Because this means you cannot put point or the mark at the
beginning of the first line of the text you want to sort, this command
uses an unusual definition of "region": all of the line point is in is
considered part of the region, and so is all of the line the mark is in,
as well as all the lines in between.

   For example, to sort a table by information found in columns 10 to
15, you could put the mark on column 10 in the first line of the table,
and point on column 15 in the last line of the table, and then run
`sort-columns'.  Equivalently, you could run it with the mark on column
15 in the first line and point on column 10 in the last line.

   This can be thought of as sorting the rectangle specified by point
and the mark, except that the text on each line to the left or right of
the rectangle moves along with the text inside the rectangle.  *Note
Rectangles::.

   Many of the sort commands ignore case differences when comparing, if
`sort-fold-case' is non-`nil'.


File: emacs,  Node: Picture Mode,  Next: Editing Binary Files,  Prev: Sorting,  Up: Top

40 Editing Pictures
*******************

To edit a picture made out of text characters (for example, a picture
of the division of a register into fields, as a comment in a program),
use the command `M-x picture-mode' to enter Picture mode.

   In Picture mode, editing is based on the "quarter-plane" model of
text, according to which the text characters lie studded on an area that
stretches infinitely far to the right and downward.  The concept of the
end of a line does not exist in this model; the most you can say is
where the last nonblank character on the line is found.

   Of course, Emacs really always considers text as a sequence of
characters, and lines really do have ends.  But Picture mode replaces
the most frequently-used commands with variants that simulate the
quarter-plane model of text.  They do this by inserting spaces or by
converting tabs to spaces.

   Most of the basic editing commands of Emacs are redefined by Picture
mode to do essentially the same thing but in a quarter-plane way.  In
addition, Picture mode defines various keys starting with the `C-c'
prefix to run special picture editing commands.

   One of these keys, `C-c C-c', is particularly important.  Often a
picture is part of a larger file that is usually edited in some other
major mode.  Picture mode records the name of the previous major mode
so you can use the `C-c C-c' command (`picture-mode-exit') later to go
back to that mode.  `C-c C-c' also deletes spaces from the ends of
lines, unless given a numeric argument.

   The special commands of Picture mode all work in other modes
(provided the `picture' library is loaded), but are not bound to keys
except in Picture mode.  The descriptions below talk of moving "one
column" and so on, but all the picture mode commands handle numeric
arguments as their normal equivalents do.

   Turning on Picture mode runs the hook `picture-mode-hook'.
Additional extensions to Picture mode can be found in `artist.el'.

* Menu:

* Basic Picture::         Basic concepts and simple commands of Picture Mode.
* Insert in Picture::     Controlling direction of cursor motion
                            after "self-inserting" characters.
* Tabs in Picture::       Various features for tab stops and indentation.
* Rectangles in Picture:: Clearing and superimposing rectangles.


File: emacs,  Node: Basic Picture,  Next: Insert in Picture,  Up: Picture Mode

40.1 Basic Editing in Picture Mode
==================================

Most keys do the same thing in Picture mode that they usually do, but
do it in a quarter-plane style.  For example, `C-f' is rebound to run
`picture-forward-column', a command which moves point one column to the
right, inserting a space if necessary so that the actual end of the
line makes no difference.  `C-b' is rebound to run
`picture-backward-column', which always moves point left one column,
converting a tab to multiple spaces if necessary.  `C-n' and `C-p' are
rebound to run `picture-move-down' and `picture-move-up', which can
either insert spaces or convert tabs as necessary to make sure that
point stays in exactly the same column.  `C-e' runs
`picture-end-of-line', which moves to after the last nonblank character
on the line.  `C-a' runs `picture-beginning-of-line'.  (The choice of
screen model does not affect beginnings of lines; the only extra thing
this command does is update the current picture column to 0.)

   Insertion of text is adapted to the quarter-plane screen model
through the use of Overwrite mode (*note Minor Modes::.)
Self-inserting characters replace existing text, column by column,
rather than pushing existing text to the right.  <RET> runs
`picture-newline', which just moves to the beginning of the following
line so that new text will replace that line.

   In Picture mode, the commands that normally delete or kill text,
instead erase text (replacing it with spaces).  <DEL>
(`picture-backward-clear-column') replaces the preceding character with
a space rather than removing it; this moves point backwards.  `C-d'
(`picture-clear-column') replaces the next character or characters with
spaces, but does not move point.  (If you want to clear characters to
spaces and move forward over them, use <SPC>.)  `C-k'
(`picture-clear-line') really kills the contents of lines, but does not
delete the newlines from the buffer.

   To do actual insertion, you must use special commands.  `C-o'
(`picture-open-line') creates a blank line after the current line; it
never splits a line.  `C-M-o' (`split-line') makes sense in Picture
mode, so it is not changed.  `C-j' (`picture-duplicate-line') inserts
another line with the same contents below the current line.

   To do actual deletion in Picture mode, use `C-w', `C-c C-d' (which
is defined as `delete-char', as `C-d' is in other modes), or one of the
picture rectangle commands (*note Rectangles in Picture::).


File: emacs,  Node: Insert in Picture,  Next: Tabs in Picture,  Prev: Basic Picture,  Up: Picture Mode

40.2 Controlling Motion after Insert
====================================

Since "self-inserting" characters in Picture mode overwrite and move
point, there is no essential restriction on how point should be moved.
Normally point moves right, but you can specify any of the eight
orthogonal or diagonal directions for motion after a "self-inserting"
character.  This is useful for drawing lines in the buffer.

`C-c <'
`C-c <LEFT>'
     Move left after insertion (`picture-movement-left').

`C-c >'
`C-c <RIGHT>'
     Move right after insertion (`picture-movement-right').

`C-c ^'
`C-c <UP>'
     Move up after insertion (`picture-movement-up').

`C-c .'
`C-c <DOWN>'
     Move down after insertion (`picture-movement-down').

`C-c `'
`C-c <HOME>'
     Move up and left ("northwest") after insertion
     (`picture-movement-nw').

`C-c ''
`C-c <prior>'
     Move up and right ("northeast") after insertion
     (`picture-movement-ne').

`C-c /'
`C-c <END>'
     Move down and left ("southwest") after insertion
     (`picture-movement-sw').

`C-c \'
`C-c <next>'
     Move down and right ("southeast") after insertion
     (`picture-movement-se').

   Two motion commands move based on the current Picture insertion
direction.  The command `C-c C-f' (`picture-motion') moves in the same
direction as motion after "insertion" currently does, while `C-c C-b'
(`picture-motion-reverse') moves in the opposite direction.


File: emacs,  Node: Tabs in Picture,  Next: Rectangles in Picture,  Prev: Insert in Picture,  Up: Picture Mode

40.3 Picture Mode Tabs
======================

Two kinds of tab-like action are provided in Picture mode.  Use
`M-<TAB>' (`picture-tab-search') for context-based tabbing.  With no
argument, it moves to a point underneath the next "interesting"
character that follows whitespace in the previous nonblank line.
"Next" here means "appearing at a horizontal position greater than the
one point starts out at".  With an argument, as in `C-u M-<TAB>', this
command moves to the next such interesting character in the current
line.  `M-<TAB>' does not change the text; it only moves point.
"Interesting" characters are defined by the variable
`picture-tab-chars', which should define a set of characters.  The
syntax for this variable is like the syntax used inside of `[...]' in a
regular expression--but without the `[' and the `]'.  Its default value
is `"!-~"'.

   <TAB> itself runs `picture-tab', which operates based on the current
tab stop settings; it is the Picture mode equivalent of
`tab-to-tab-stop'.  Normally it just moves point, but with a numeric
argument it clears the text that it moves over.

   The context-based and tab-stop-based forms of tabbing are brought
together by the command `C-c <TAB>' (`picture-set-tab-stops').  This
command sets the tab stops to the positions which `M-<TAB>' would
consider significant in the current line.  The use of this command,
together with <TAB>, can get the effect of context-based tabbing.  But
`M-<TAB>' is more convenient in the cases where it is sufficient.

   It may be convenient to prevent use of actual tab characters in
pictures.  For example, this prevents `C-x <TAB>' from messing up the
picture.  You can do this by setting the variable `indent-tabs-mode' to
`nil'.


File: emacs,  Node: Rectangles in Picture,  Prev: Tabs in Picture,  Up: Picture Mode

40.4 Picture Mode Rectangle Commands
====================================

Picture mode defines commands for working on rectangular pieces of the
text in ways that fit with the quarter-plane model.  The standard
rectangle commands may also be useful.  *Note Rectangles::.

`C-c C-k'
     Clear out the region-rectangle with spaces
     (`picture-clear-rectangle').  With a prefix argument, delete the
     text.

`C-c C-w R'
     Similar, but save rectangle contents in register R first
     (`picture-clear-rectangle-to-register').

`C-c C-y'
     Copy last killed rectangle into the buffer by overwriting, with
     upper left corner at point (`picture-yank-rectangle').  With
     argument, insert instead.

`C-c C-x R'
     Similar, but use the rectangle in register R
     (`picture-yank-rectangle-from-register').

   The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
standard rectangle commands in that they normally clear the rectangle
instead of deleting it; this is analogous with the way `C-d' is changed
in Picture mode.

   However, deletion of rectangles can be useful in Picture mode, so
these commands delete the rectangle if given a numeric argument.  `C-c
C-k' either with or without a numeric argument saves the rectangle for
`C-c C-y'.

   The Picture mode commands for yanking rectangles differ from the
standard ones in that they overwrite instead of inserting.  This is the
same way that Picture mode insertion of other text differs from other
modes.  `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
the rectangle that was most recently killed, while `C-c C-x'
(`picture-yank-rectangle-from-register') does likewise for the
rectangle found in a specified register.


File: emacs,  Node: Editing Binary Files,  Next: Saving Emacs Sessions,  Prev: Picture Mode,  Up: Top

41 Editing Binary Files
***********************

There is a special major mode for editing binary files: Hexl mode.  To
use it, use `M-x hexl-find-file' instead of `C-x C-f' to visit the
file.  This command converts the file's contents to hexadecimal and
lets you edit the translation.  When you save the file, it is converted
automatically back to binary.

   You can also use `M-x hexl-mode' to translate an existing buffer
into hex.  This is useful if you visit a file normally and then discover
it is a binary file.

   Ordinary text characters overwrite in Hexl mode.  This is to reduce
the risk of accidentally spoiling the alignment of data in the file.
There are special commands for insertion.  Here is a list of the
commands of Hexl mode:

`C-M-d'
     Insert a byte with a code typed in decimal.

`C-M-o'
     Insert a byte with a code typed in octal.

`C-M-x'
     Insert a byte with a code typed in hex.

`C-x ['
     Move to the beginning of a 1k-byte "page".

`C-x ]'
     Move to the end of a 1k-byte "page".

`M-g'
     Move to an address specified in hex.

`M-j'
     Move to an address specified in decimal.

`C-c C-c'
     Leave Hexl mode, going back to the major mode this buffer had
     before you invoked `hexl-mode'.

Other Hexl commands let you insert strings (sequences) of binary bytes,
move by `short's or `int's, etc.; type `C-h a hexl-<RET>' for details.


File: emacs,  Node: Saving Emacs Sessions,  Next: Recursive Edit,  Prev: Editing Binary Files,  Up: Top

42 Saving Emacs Sessions
************************

Use the desktop library to save the state of Emacs from one session to
another.  Once you save the Emacs "desktop"--the buffers, their file
names, major modes, buffer positions, and so on--then subsequent Emacs
sessions reload the saved desktop.

   You can save the desktop manually with the command `M-x
desktop-save'.  You can also enable automatic saving of the desktop
when you exit Emacs, and automatic restoration of the last saved
desktop when Emacs starts: use the Customization buffer (*note Easy
Customization::) to set `desktop-save-mode' to `t' for future sessions,
or add this line in your init file (*note Init File::):

     (desktop-save-mode 1)

   If you turn on `desktop-save-mode' in your init file, then when
Emacs starts, it looks for a saved desktop in the current directory.
(More precisely, it looks in the directories specified by DESKTOP-PATH,
and uses the first desktop it finds.)  Thus, you can have separate
saved desktops in different directories, and the starting directory
determines which one Emacs reloads.  You can save the current desktop
and reload one saved in another directory by typing `M-x
desktop-change-dir'.  Typing `M-x desktop-revert' reverts to the
desktop previously reloaded.

   Specify the option `--no-desktop' on the command line when you don't
want it to reload any saved desktop.  This turns off
`desktop-save-mode' for the current session.  Starting Emacs with the
`--no-init-file' option also disables desktop reloading, since it
bypasses the init file, where `desktop-save-mode' is usually turned on.

   By default, all the buffers in the desktop are restored at one go.
However, this may be slow if there are a lot of buffers in the desktop.
You can specify the maximum number of buffers to restore immediately
with the variable `desktop-restore-eager'; the remaining buffers are
restored "lazily", when Emacs is idle.

   Type `M-x desktop-clear' to empty the Emacs desktop.  This kills all
buffers except for internal ones, and clears the global variables
listed in `desktop-globals-to-clear'.  If you want this to preserve
certain buffers, customize the variable
`desktop-clear-preserve-buffers-regexp', whose value is a regular
expression matching the names of buffers not to kill.

   If you want to save minibuffer history from one session to another,
use the `savehist' library.


File: emacs,  Node: Recursive Edit,  Next: Emulation,  Prev: Saving Emacs Sessions,  Up: Top

43 Recursive Editing Levels
***************************

A "recursive edit" is a situation in which you are using Emacs commands
to perform arbitrary editing while in the middle of another Emacs
command.  For example, when you type `C-r' inside of a `query-replace',
you enter a recursive edit in which you can change the current buffer.
On exiting from the recursive edit, you go back to the `query-replace'.

   "Exiting" the recursive edit means returning to the unfinished
command, which continues execution.  The command to exit is `C-M-c'
(`exit-recursive-edit').

   You can also "abort" the recursive edit.  This is like exiting, but
also quits the unfinished command immediately.  Use the command `C-]'
(`abort-recursive-edit') to do this.  *Note Quitting::.

   The mode line shows you when you are in a recursive edit by
displaying square brackets around the parentheses that always surround
the major and minor mode names.  Every window's mode line shows this in
the same way, since being in a recursive edit is true of Emacs as a
whole rather than any particular window or buffer.

   It is possible to be in recursive edits within recursive edits.  For
example, after typing `C-r' in a `query-replace', you may type a
command that enters the debugger.  This begins a recursive editing level
for the debugger, within the recursive editing level for `C-r'.  Mode
lines display a pair of square brackets for each recursive editing
level currently in progress.

   Exiting the inner recursive edit (such as with the debugger `c'
command) resumes the command running in the next level up.  When that
command finishes, you can then use `C-M-c' to exit another recursive
editing level, and so on.  Exiting applies to the innermost level only.
Aborting also gets out of only one level of recursive edit; it returns
immediately to the command level of the previous recursive edit.  If you
wish, you can then abort the next recursive editing level.

   Alternatively, the command `M-x top-level' aborts all levels of
recursive edits, returning immediately to the top-level command reader.
It also exits the minibuffer, if it is active.

   The text being edited inside the recursive edit need not be the same
text that you were editing at top level.  It depends on what the
recursive edit is for.  If the command that invokes the recursive edit
selects a different buffer first, that is the buffer you will edit
recursively.  In any case, you can switch buffers within the recursive
edit in the normal manner (as long as the buffer-switching keys have
not been rebound).  You could probably do all the rest of your editing
inside the recursive edit, visiting files and all.  But this could have
surprising effects (such as stack overflow) from time to time.  So
remember to exit or abort the recursive edit when you no longer need it.

   In general, we try to minimize the use of recursive editing levels in
GNU Emacs.  This is because they constrain you to "go back" in a
particular order--from the innermost level toward the top level.  When
possible, we present different activities in separate buffers so that
you can switch between them as you please.  Some commands switch to a
new major mode which provides a command to switch back.  These
approaches give you more flexibility to go back to unfinished tasks in
the order you choose.


File: emacs,  Node: Emulation,  Next: Hyperlinking,  Prev: Recursive Edit,  Up: Top

44 Emulation
************

GNU Emacs can be programmed to emulate (more or less) most other
editors.  Standard facilities can emulate these:

CRiSP/Brief (PC editor)
     `M-x crisp-mode' enables key bindings to emulate the CRiSP/Brief
     editor.  Note that this rebinds `M-x' to exit Emacs unless you set
     the variable `crisp-override-meta-x'.  You can also use the
     command `M-x scroll-all-mode' or set the variable
     `crisp-load-scroll-all' to emulate CRiSP's scroll-all feature
     (scrolling all windows together).

EDT (DEC VMS editor)
     Turn on EDT emulation with `M-x edt-emulation-on'; restore normal
     command bindings with `M-x edt-emulation-off'.

     Most of the EDT emulation commands are keypad keys, and most
     standard Emacs key bindings are still available.  The EDT
     emulation rebindings are done in the global keymap, so there is no
     problem switching buffers or major modes while in EDT emulation.

TPU (DEC VMS editor)
     `M-x tpu-edt-on' turns on emulation of the TPU editor emulating
     EDT.

vi (Berkeley editor)
     Viper is the newest emulator for vi.  It implements several levels
     of emulation; level 1 is closest to vi itself, while level 5
     departs somewhat from strict emulation to take advantage of the
     capabilities of Emacs.  To invoke Viper, type `M-x viper-mode'; it
     will guide you the rest of the way and ask for the emulation
     level.  *note Viper: (viper)Top.

vi (another emulator)
     `M-x vi-mode' enters a major mode that replaces the previously
     established major mode.  All of the vi commands that, in real vi,
     enter "input" mode are programmed instead to return to the
     previous major mode.  Thus, ordinary Emacs serves as vi's "input"
     mode.

     Because vi emulation works through major modes, it does not work
     to switch buffers during emulation.  Return to normal Emacs first.

     If you plan to use vi emulation much, you probably want to bind a
     key to the `vi-mode' command.

vi (alternate emulator)
     `M-x vip-mode' invokes another vi emulator, said to resemble real
     vi more thoroughly than `M-x vi-mode'.  "Input" mode in this
     emulator is changed from ordinary Emacs so you can use <ESC> to go
     back to emulated vi command mode.  To get from emulated vi command
     mode back to ordinary Emacs, type `C-z'.

     This emulation does not work through major modes, and it is
     possible to switch buffers in various ways within the emulator.
     It is not so necessary to assign a key to the command `vip-mode' as
     it is with `vi-mode' because terminating insert mode does not use
     it.

     *note VIP: (vip)Top, for full information.

WordStar (old wordprocessor)
     `M-x wordstar-mode' provides a major mode with WordStar-like key
     bindings.


File: emacs,  Node: Hyperlinking,  Next: Amusements,  Prev: Emulation,  Up: Top

45 Hyperlinking and Navigation Features
***************************************

The following subsections describe convenience features for handling
URLs and other types of links occurring in Emacs buffer text.

* Menu:

* Browse-URL::                  Following URLs.
* Goto Address mode::           Activating URLs.
* FFAP::                        Finding files etc. at point.


File: emacs,  Node: Browse-URL,  Next: Goto Address mode,  Up: Hyperlinking

45.1 Following URLs
===================

`M-x browse-url <RET> URL <RET>'
     Load a URL into a Web browser.

   The Browse-URL package allows you to easily follow URLs from within
Emacs.  Most URLs are followed by invoking a web browser; `mailto:'
URLs are followed by invoking the `compose-mail' Emacs command to send
mail to the specified address (*note Sending Mail::).

   The command `M-x browse-url' prompts for a URL, and follows it.  If
point is located near a plausible URL, that URL is offered as the
default.  The Browse-URL package also provides other commands which you
might like to bind to keys, such as `browse-url-at-point' and
`browse-url-at-mouse'.

   You can customize Browse-URL's behavior via various options in the
`browse-url' Customize group.  In particular, the option
`browse-url-mailto-function' lets you define how to follow `mailto:'
URLs, while `browse-url-browser-function' lets you define how to follow
other types of URLs.  For more information, view the package commentary
by typing `C-h P browse-url <RET>'.


File: emacs,  Node: Goto Address mode,  Next: FFAP,  Prev: Browse-URL,  Up: Hyperlinking

45.2 Activating URLs
====================

`M-x goto-address-mode'
     Activate URLs and e-mail addresses in the current buffer.

   You can make Emacs mark out URLs specially in the current buffer, by
typing `M-x goto-address-mode'.  When this buffer-local minor mode is
enabled, it finds all the URLs in the buffer, highlights them, and
turns them into clickable buttons.  You can follow the URL by typing
`C-c <RET>' (`goto-address-at-point') while point is on its text; or by
clicking with `Mouse-2', or by clicking `Mouse-1' quickly (*note Mouse
References::).  Following a URL is done by calling `browse-url' as a
subroutine (*note Browse-URL::).

   It can be useful to add `goto-address-mode' to mode hooks and hooks
for displaying an incoming message (e.g. `rmail-show-message-hook' for
Rmail, and `mh-show-mode-hook' for MH-E).  This is not needed for Gnus,
which has a similar feature of its own.


File: emacs,  Node: FFAP,  Prev: Goto Address mode,  Up: Hyperlinking

45.3 Finding Files and URLs at Point
====================================

The FFAP package replaces certain key bindings for finding files, such
as `C-x C-f', with commands that provide more sensitive defaults.
These commands behave like the ordinary ones when given a prefix
argument.  Otherwise, they get the default file name or URL from the
text around point.  If what is found in the buffer has the form of a
URL rather than a file name, the commands use `browse-url' to view it
(*note Browse-URL::).

   This feature is useful for following references in mail or news
buffers, `README' files, `MANIFEST' files, and so on.  For more
information, view the package commentary by typing `C-h P ffap <RET>'.

   To enable FFAP, type `M-x ffap-bindings'.  This makes the following
key bindings, and also installs hooks for additional FFAP functionality
in Rmail, Gnus and VM article buffers.

`C-x C-f FILENAME <RET>'
     Find FILENAME, guessing a default from text around point
     (`find-file-at-point').

`C-x C-r'
     `ffap-read-only', analogous to `find-file-read-only'.

`C-x C-v'
     `ffap-alternate-file', analogous to `find-alternate-file'.

`C-x d DIRECTORY <RET>'
     Start Dired on DIRECTORY, defaulting to the directory name at
     point (`dired-at-point').

`C-x C-d'
     `ffap-list-directory', analogous to `list-directory'.

`C-x 4 f'
     `ffap-other-window', analogous to `find-file-other-window'.

`C-x 4 r'
     `ffap-read-only-other-window', analogous to
     `find-file-read-only-other-window'.

`C-x 4 d'
     `ffap-dired-other-window', like `dired-other-window'.

`C-x 5 f'
     `ffap-other-frame', analogous to `find-file-other-frame'.

`C-x 5 r'
     `ffap-read-only-other-frame', analogous to
     `find-file-read-only-other-frame'.

`C-x 5 d'
     `ffap-dired-other-frame', analogous to `dired-other-frame'.

`M-x ffap-next'
     Search buffer for next file name or URL, then find that file or
     URL.

`S-Mouse-3'
     `ffap-at-mouse' finds the file guessed from text around the
     position of a mouse click.

`C-S-Mouse-3'
     Display a menu of files and URLs mentioned in current buffer, then
     find the one you select (`ffap-menu').


File: emacs,  Node: Amusements,  Next: Packages,  Prev: Hyperlinking,  Up: Top

46 Other Amusements
*******************

The `animate' package makes text dance (e.g.  `M-x
animate-birthday-present').

   `M-x blackbox', `M-x mpuz' and `M-x 5x5' are puzzles.  `blackbox'
challenges you to determine the location of objects inside a box by
tomography.  `mpuz' displays a multiplication puzzle with letters
standing for digits in a code that you must guess--to guess a value,
type a letter and then the digit you think it stands for.  The aim of
`5x5' is to fill in all the squares.

   `M-x bubbles' is a game in which the object is to remove as many
bubbles as you can in the smallest number of moves.

   `M-x decipher' helps you to cryptanalyze a buffer which is encrypted
in a simple monoalphabetic substitution cipher.

   `M-x dissociated-press' scrambles the text in the current Emacs
buffer, word by word or character by character, writing its output to a
buffer named `*Dissociation*'.  A positive argument tells it to operate
character by character, and specifies the number of overlap characters.
A negative argument tells it to operate word by word, and specifies the
number of overlap words.  Dissociated Press produces results fairly
like those of a Markov chain, but is however, an independent,
ignoriginal invention; it techniquitously copies several consecutive
characters from the sample text between random jumps, unlike a Markov
chain which would jump randomly after each word or character.  Keep
dissociwords out of your documentation, if you want it to be well
userenced and properbose.

   `M-x dunnet' runs an text-based adventure game.

   If you want a little more personal involvement, try `M-x gomoku',
which plays the game Go Moku with you.

   If you are a little bit bored, you can try `M-x hanoi'.  If you are
considerably bored, give it a numeric argument.  If you are very, very
bored, try an argument of 9.  Sit back and watch.

   `M-x life' runs Conway's "Life" cellular automaton.

   `M-x landmark' runs a relatively non-participatory game in which a
robot attempts to maneuver towards a tree at the center of the window
based on unique olfactory cues from each of the four directions.

   `M-x morse-region' converts the text in the region to Morse code;
`M-x unmorse-region' converts it back.  `M-x nato-region' converts the
text in the region to NATO phonetic alphabet; `M-x denato-region'
converts it back.

   `M-x pong', `M-x snake' and `M-x tetris' are implementations of the
well-known Pong, Snake and Tetris games.

   `M-x solitaire' plays a game of solitaire in which you jump pegs
across other pegs.

   The command `M-x zone' plays games with the display when Emacs is
idle.

   Finally, if you find yourself frustrated, try describing your
problems to the famous psychotherapist Eliza.  Just do `M-x doctor'.
End each input by typing <RET> twice.


File: emacs,  Node: Packages,  Next: Customization,  Prev: Amusements,  Up: Top

47 Emacs Lisp Packages
**********************

Emacs includes a facility that lets you easily download and install
"packages" that implement additional features.  Each package is a
separate Emacs Lisp program, sometimes including other components such
as an Info manual.

   `M-x list-packages' brings up a buffer named `*Packages*' with a
list of all packages.  You can install or uninstall packages via this
buffer.  *Note Package Menu::.

   The command `C-h P' (`describe-package') prompts for the name of a
package, and displays a help buffer describing the attributes of the
package and the features that it implements.

   By default, Emacs downloads packages from a "package archive"
maintained by the Emacs developers and hosted by the GNU project.
Optionally, you can also download packages from archives maintained by
third parties.  *Note Package Installation::.

   For information about turning an Emacs Lisp program into an
installable package, *Note Packaging: (elisp)Packaging.  For
information about finding third-party packages and other Emacs Lisp
extensions, *Note Packages that do not come with Emacs: (efaq)Packages
that do not come with Emacs.

* Menu:

* Package Menu::         Buffer for viewing and managing packages.
* Package Installation:: Options for package installation.
* Package Files::        Where packages are installed.


File: emacs,  Node: Package Menu,  Next: Package Installation,  Up: Packages

47.1 The Package Menu Buffer
============================

The command `M-x list-packages' brings up the "package menu".  This is
a buffer listing all the packages that Emacs knows about, one on each
line, with the following information:

   * The package name (e.g. `auctex').

   * The package's version number (e.g. `11.86').

   * The package's status--normally one of `available' (can be
     downloaded from the package archive), `installed', or `built-in'
     (included in Emacs by default).

     In some instances, the status can be `held', `disabled', or
     `obsolete'.  *Note Package Installation::.

   * A short description of the package.

The `list-packages' command accesses the network, to retrieve the list
of available packages from the package archive server.  If the network
is unavailable, it falls back on the most recently retrieved list.

   The following commands are available in the package menu:

`h'
     Print a short message summarizing how to use the package menu
     (`package-menu-quick-help').

`?'
`<RET>'
     Display a help buffer for the package on the current line
     (`package-menu-describe-package'), similar to the help window
     displayed by the `C-h P' command (*note Packages::).

`i'
     Mark the package on the current line for installation
     (`package-menu-mark-install').  If the package status is
     `available', this adds an `I' character to the start of the line;
     typing `x' (see below) will download and install the package.

`d'
     Mark the package on the current line for deletion
     (`package-menu-mark-delete').  If the package status is
     `installed', this adds a `D' character to the start of the line;
     typing `x' (see below) will delete the package.  *Note Package
     Files::, for information about what package deletion entails.

`u'
     Remove any installation or deletion mark previously added to the
     current line by an `i' or `d' command.

`U'
     Mark all package with a newer available version for "upgrading"
     (`package-menu-mark-upgrades').  This places an installation mark
     on the new available versions, and a deletion mark on the old
     installed versions.

`x'
     Download and install all packages marked with `i', and their
     dependencies; also, delete all packages marked with `d'
     (`package-menu-execute').  This also removes the marks.

`r'
     Refresh the package list (`package-menu-refresh').  This fetches
     the list of available packages from the package archive again, and
     recomputes the package list.

For example, you can install a package by typing `i' on the line
listing that package, followed by `x'.


File: emacs,  Node: Package Installation,  Next: Package Files,  Prev: Package Menu,  Up: Packages

47.2 Package Installation
=========================

Packages are most conveniently installed using the package menu (*note
Package Menu::), but you can also use the command `M-x
package-install'.  This prompts for the name of a package with the
`available' status, then downloads and installs it.

   A package may "require" certain other packages to be installed,
because it relies on functionality provided by them.  When Emacs
installs such a package, it also automatically downloads and installs
any required package that is not already installed.  (If a required
package is somehow unavailable, Emacs signals an error and stops
installation.)  A package's requirements list is shown in its help
buffer.

   By default, packages are downloaded from a single package archive
maintained by the Emacs developers.  This is controlled by the variable
`package-archives', whose value is a list of package archives known to
Emacs.  Each list element must have the form `(ID . LOCATION)', where
ID is the name of a package archive and LOCATION is the HTTP address or
directory name of the package archive.  You can alter this list if you
wish to use third party package archives--but do so at your own risk,
and use only third parties that you think you can trust!

   Once a package is downloaded and installed, it is "loaded" into the
current Emacs session.  Loading a package is not quite the same as
loading a Lisp library (*note Lisp Libraries::); its effect varies from
package to package.  Most packages just make some new commands
available, while others have more wide-ranging effects on the Emacs
session.  For such information, consult the package's help buffer.

   By default, Emacs also automatically loads all installed packages in
subsequent Emacs sessions.  This happens at startup, after processing
the init file (*note Init File::).  As an exception, Emacs does not
load packages at startup if invoked with the `-q' or `--no-init-file'
options (*note Initial Options::).

   To disable automatic package loading, change the variable
`package-enable-at-startup' to `nil'.

   The reason automatic package loading occurs after loading the init
file is that user options only receive their customized values after
loading the init file, including user options which affect the
packaging system.  In some circumstances, you may want to load packages
explicitly in your init file (usually because some other code in your
init file depends on a package).  In that case, your init file should
call the function `package-initialize'.  It is up to you to ensure that
relevant user options, such as `package-load-list' (see below), are set
up prior to the `package-initialize' call.  You should also set
`package-enable-at-startup' to `nil', to avoid loading the packages
again after processing the init file.  Alternatively, you may choose to
completely inhibit package loading at startup, and invoke the command
`M-x package-initialize' to load your packages manually.

   For finer control over package loading, you can use the variable
`package-load-list'.  Its value should be a list.  A list element of
the form `(NAME VERSION)' tells Emacs to load version VERSION of the
package named NAME.  Here, VERSION should be a version string
(corresponding to a specific version of the package), or `t' (which
means to load any installed version), or `nil' (which means no version;
this "disables" the package, preventing it from being loaded).  A list
element can also be the symbol `all', which means to load the latest
installed version of any package not named by the other list elements.
The default value is just `'(all)'.

   For example, if you set `package-load-list' to `'((muse "3.20")
all)', then Emacs only loads version 3.20 of the `muse' package, plus
any installed version of packages other than `muse'.  Any other version
of `muse' that happens to be installed will be ignored.  The `muse'
package will be listed in the package menu with the `held' status.


File: emacs,  Node: Package Files,  Prev: Package Installation,  Up: Packages

47.3 Package Files and Directory Layout
=======================================

Each package is downloaded from the package archive in the form of a
single "package file"--either an Emacs Lisp source file, or a tar file
containing multiple Emacs Lisp source and other files.  Package files
are automatically retrieved, processed, and disposed of by the Emacs
commands that install packages.  Normally, you will not need to deal
directly with them, unless you are making a package (*note Packaging:
(elisp)Packaging.).  Should you ever need to install a package directly
from a package file, use the command `M-x package-install-file'.

   Once installed, the contents of a package are placed in a
subdirectory of `~/.emacs.d/elpa/' (you can change the name of that
directory by changing the variable `package-user-dir').  The package
subdirectory is named `NAME-VERSION', where NAME is the package name
and VERSION is its version string.

   In addition to `package-user-dir', Emacs looks for installed
packages in the directories listed in `package-directory-list'.  These
directories are meant for system administrators to make Emacs packages
available system-wide; Emacs itself never installs packages there.  The
package subdirectories for `package-directory-list' are laid out in the
same way as in `package-user-dir'.

   Deleting a package (*note Package Menu::) involves deleting the
corresponding package subdirectory.  This only works for packages
installed in `package-user-dir'; if told to act on a package in a
system-wide package directory, the deletion command signals an error.


File: emacs,  Node: Customization,  Next: Quitting,  Prev: Packages,  Up: Top

48 Customization
****************

This chapter describes some simple methods to customize the behavior of
Emacs.

   Apart from the methods described here, see *note X Resources:: for
information about using X resources to customize Emacs, and see *note
Keyboard Macros:: for information about recording and replaying
keyboard macros.  Making more far-reaching and open-ended changes
involves writing Emacs Lisp code; see *note Emacs Lisp: (elisp)Top.

* Menu:

* Easy Customization::  Convenient way to browse and change settings.
* Variables::           Many Emacs commands examine Emacs variables
                          to decide what to do; by setting variables,
                          you can control their functioning.
* Key Bindings::        The keymaps say what command each key runs.
                          By changing them, you can "redefine keys".
* Init File::           How to write common customizations in the
                          initialization file.


File: emacs,  Node: Easy Customization,  Next: Variables,  Up: Customization

48.1 Easy Customization Interface
=================================

Emacs has many "settings" which you can change.  Most settings are
"customizable variables" (*note Variables::), which are also called
"user options".  There is a huge number of customizable variables,
controlling numerous aspects of Emacs behavior; the variables
documented in this manual are listed in *note Variable Index::.  A
separate class of settings are the "faces", which determine the fonts,
colors, and other attributes of text (*note Faces::).

   To browse and alter settings (both variables and faces), type `M-x
customize'.  This creates a "customization buffer", which lets you
navigate through a logically organized list of settings, edit and set
their values, and save them permanently.

* Menu:

* Customization Groups::     How settings are classified.
* Browsing Custom::          Browsing and searching for settings.
* Changing a Variable::      How to edit an option's value and set the option.
* Saving Customizations::    Saving customizations for future Emacs sessions.
* Face Customization::       How to edit the attributes of a face.
* Specific Customization::   Customizing specific settings or groups.
* Custom Themes::            Collections of customization settings.
* Creating Custom Themes::   How to create a new custom theme.


File: emacs,  Node: Customization Groups,  Next: Browsing Custom,  Up: Easy Customization

48.1.1 Customization Groups
---------------------------

Customization settings are organized into "customization groups".
These groups are collected into bigger groups, all the way up to a
master group called `Emacs'.

   `M-x customize' creates a customization buffer that shows the
top-level `Emacs' group.  It looks like this, in part:

     To apply changes, use the Save or Set buttons.
     For details, see [Saving Customizations] in the [Emacs manual].

     ________________________________________ [ Search ]

      Operate on all settings in this buffer:
      [ Set for current session ] [ Save for future sessions ]
      [ Undo edits ] [ Reset to saved ] [ Erase customizations ] [ Exit ]


     Emacs group: Customization of the One True Editor.
           [State]: visible group members are all at standard values.
           See also [Manual].

     [Editing] : Basic text editing facilities.

     [Convenience] : Convenience features for faster editing.

     MORE SECOND-LEVEL GROUPS

The main part of this buffer shows the `Emacs' customization group,
which contains several other groups (`Editing', `Convenience', etc.).
The contents of those groups are not listed here, only one line of
documentation each.

   The "state" of the group indicates whether setting in that group has
been edited, set or saved.  *Note Changing a Variable::.

   Most of the customization buffer is read-only, but it includes some
"editable fields" that you can edit.  For example, at the top of the
customization buffer is an editable field for searching for settings
(*note Browsing Custom::).  There are also "buttons" and "links", which
you can activate by either clicking with the mouse, or moving point
there and typing <RET>.  For example, the group names like `[Editing]'
are links; activating one of these links brings up the customization
buffer for that group.

   In the customizable buffer, you can type <TAB> (`widget-forward') to
move forward to the next button or editable field.  `S-<TAB>'
(`widget-backward') moves back to the previous button or editable field.


File: emacs,  Node: Browsing Custom,  Next: Changing a Variable,  Prev: Customization Groups,  Up: Easy Customization

48.1.2 Browsing and Searching for Settings
------------------------------------------

From the top-level customization buffer created by `M-x customize', you
can follow the links to the subgroups of the `Emacs' customization
group.  These subgroups may contain settings for you to customize; they
may also contain further subgroups, dealing with yet more specialized
subsystems of Emacs.  As you navigate the hierarchy of customization
groups, you should find some settings that you want to customize.

   If you are interested in customizing a particular setting or
customization group, you can go straight there with the commands `M-x
customize-option', `M-x customize-face', or `M-x customize-group'.
*Note Specific Customization::.

   If you don't know exactly what groups or settings you want to
customize, you can search for them using the editable search field at
the top of each customization buffer.  Here, you can type in a search
term--either one or more words separated by spaces, or a regular
expression (*note Regexps::).  Then type <RET> in the field, or
activate the `Search' button next to it, to switch to a customization
buffer containing groups and settings that match those terms.  Note,
however, that this feature only finds groups and settings that are
loaded in the current Emacs session.

   If you don't want customization buffers to show the search field,
change the variable `custom-search-field' to `nil'.

   The command `M-x customize-apropos' is similar to using the search
field, except that it reads the search term(s) using the minibuffer.
*Note Specific Customization::.

   `M-x customize-browse' is another way to browse the available
settings.  This command creates a special customization buffer which
shows only the names of groups and settings, in a structured layout.
You can show the contents of a group, in the same buffer, by invoking
the `[+]' button next to the group name.  When the group contents are
shown, the button changes to `[-]'; invoking that hides the group
contents again.  Each group or setting in this buffer has a link which
says `[Group]', `[Option]' or `[Face]'.  Invoking this link creates an
ordinary customization buffer showing just that group, option, or face;
this is the way to change settings that you find with `M-x
customize-browse'.


File: emacs,  Node: Changing a Variable,  Next: Saving Customizations,  Prev: Browsing Custom,  Up: Easy Customization

48.1.3 Changing a Variable
--------------------------

Here is an example of what a variable, or user option, looks like in
the customization buffer:

     [Hide] Kill Ring Max: 60
        [State]: STANDARD.
        Maximum length of kill ring before oldest elements are thrown away.

   The first line shows that the variable is named `kill-ring-max',
formatted as `Kill Ring Max' for easier viewing.  Its value is `60'.
The button labeled `[Hide]', if activated, hides the variable's value
and state; this is useful to avoid cluttering up the customization
buffer with very long values (for this reason, variables that have very
long values may start out hidden).  If you use the `[Hide]' button, it
changes to `[Show Value]', which you can activate to reveal the value
and state.  On a graphical display, the `[Hide]' and `[Show Value]'
buttons are replaced with graphical triangles pointing downwards and
rightwards respectively.

   The line after the variable name indicates the "customization state"
of the variable: in this example, `STANDARD' means you have not changed
the variable, so its value is the default one.  The `[State]' button
gives a menu of operations for customizing the variable.

   Below the customization state is the documentation for the variable.
This is the same documentation that would be shown by the `C-h v'
command (*note Examining::).  If the documentation is more than one
line long, only one line may be shown.  If so, that line ends with a
`[More]' button; activate this to see the full documentation.

   To enter a new value for `Kill Ring Max', just move point to the
value and edit it.  For example, type `M-d' to delete the `60' and type
in another number.  As you begin to alter the text, the `[State]' line
will change:

     [State]: EDITED, shown value does not take effect until you
              set or save it.

Editing the value does not make it take effect right away.  To do that,
you must "set" the variable by activating the `[State]' button and
choosing `Set for Current Session'.  Then the variable's state becomes:

     [State]: SET for current session only.

You don't have to worry about specifying a value that is not valid; the
`Set for Current Session' operation checks for validity and will not
install an unacceptable value.

   While editing certain kinds of values, such as file names, directory
names, and Emacs command names, you can perform completion with `C-M-i'
(`widget-complete'), or the equivalent keys `M-<TAB>' or `<ESC> <TAB>'.
This behaves much like minibuffer completion (*note Completion::).

   Typing <RET> on an editable value field moves point forward to the
next field or button, like <TAB>.  You can thus type <RET> when you are
finished editing a field, to move on to the next button or field.  To
insert a newline within an editable field, use `C-o' or `C-q C-j'.

   For some variables, there is only a fixed set of legitimate values,
and you are not allowed to edit the value directly.  Instead, a `[Value
Menu]' button appears before the value; activating this button presents
a choice of values.  For a boolean "on or off" value, the button says
`[Toggle]', and flips the value.  After using the `[Value Menu]' or
`[Toggle]' button, you must again set the variable to make the chosen
value take effect.

   Some variables have values with complex structure.  For example, the
value of `minibuffer-frame-alist' is an association list.  Here is how
it appears in the customization buffer:

     [Hide] Minibuffer Frame Alist:
     [INS] [DEL] Parameter: width
                 Value: 80
     [INS] [DEL] Parameter: height
                 Value: 2
     [INS]
        [ State ]: STANDARD.
        Alist of parameters for the initial minibuffer frame. [Hide]
        [...more lines of documentation...]

In this case, each association in the list consists of two items, one
labeled `Parameter' and one labeled `Value'; both are editable fields.
You can delete an association from the list with the `[DEL]' button
next to it.  To add an association, use the `[INS]' button at the
position where you want to insert it; the very last `[INS]' button
inserts at the end of the list.

   When you set a variable, the new value takes effect only in the
current Emacs session.  To "save" the value for future sessions, use
the `[State]' button and select the `Save for Future Sessions'
operation.  *Note Saving Customizations::.

   You can also restore the variable to its standard value by using the
`[State]' button and selecting the `Erase Customization' operation.
There are actually four reset operations:

`Undo Edits'
     If you have modified but not yet set the variable, this restores
     the text in the customization buffer to match the actual value.

`Reset to Saved'
     This restores the value of the variable to the last saved value,
     and updates the text accordingly.

`Erase Customization'
     This sets the variable to its standard value.  Any saved value that
     you have is also eliminated.

`Set to Backup Value'
     This sets the variable to a previous value that was set in the
     customization buffer in this session.  If you customize a variable
     and then reset it, which discards the customized value, you can
     get the discarded value back again with this operation.

   Sometimes it is useful to record a comment about a specific
customization.  Use the `Add Comment' item from the `[State]' menu to
create a field for entering the comment.

   Near the top of the customization buffer are two lines of buttons:

      [Set for Current Session] [Save for Future Sessions]
      [Undo Edits] [Reset to Saved] [Erase Customization]   [Exit]

Each of the first five buttons performs the stated operation--set,
save, reset, etc.--on all the settings in the buffer that could
meaningfully be affected.  They do not operate on settings that are
hidden, nor on subgroups that are hidden or not visible in the buffer.

   The command `C-c C-c' (`Custom-set') is equivalent using to the
`[Set for Current Session]' button.  The command `C-x C-s'
(`Custom-save') is like using the `[Save for Future Sessions]' button.

   The `[Exit]' button switches out of the customization buffer, and
buries the buffer at the bottom of the buffer list.  To make it kill
the customization buffer instead, change the variable
`custom-buffer-done-kill' to `t'.


File: emacs,  Node: Saving Customizations,  Next: Face Customization,  Prev: Changing a Variable,  Up: Easy Customization

48.1.4 Saving Customizations
----------------------------

In the customization buffer, you can "save" a customization setting by
choosing the `Save for Future Sessions' choice from its `[State]'
button.  The `C-x C-s' (`Custom-save') command, or the `[Save for
Future Sessions]' button at the top of the customization buffer, saves
all applicable settings in the buffer.

   Saving works by writing code to a file, usually your initialization
file (*note Init File::).  Future Emacs sessions automatically read
this file at startup, which sets up the customizations again.

   You can choose to save customizations somewhere other than your
initialization file.  To make this work, you must add a couple of lines
of code to your initialization file, to set the variable `custom-file'
to the name of the desired file, and to load that file.  For example:

     (setq custom-file "~/.emacs-custom.el")
     (load custom-file)

   You can even specify different customization files for different
Emacs versions, like this:

     (cond ((< emacs-major-version 22)
            ;; Emacs 21 customization.
            (setq custom-file "~/.custom-21.el"))
           ((and (= emacs-major-version 22)
                 (< emacs-minor-version 3))
            ;; Emacs 22 customization, before version 22.3.
            (setq custom-file "~/.custom-22.el"))
           (t
            ;; Emacs version 22.3 or later.
            (setq custom-file "~/.emacs-custom.el")))

     (load custom-file)

   If Emacs was invoked with the `-q' or `--no-init-file' options
(*note Initial Options::), it will not let you save your customizations
in your initialization file.  This is because saving customizations
from such a session would wipe out all the other customizations you
might have on your initialization file.


File: emacs,  Node: Face Customization,  Next: Specific Customization,  Prev: Saving Customizations,  Up: Easy Customization

48.1.5 Customizing Faces
------------------------

You can customize faces (*note Faces::), which determine how Emacs
displays different types of text.  Customization groups can contain
both variables and faces.

   For example, in programming language modes, source code comments are
shown with `font-lock-comment-face' (*note Font Lock::).  In a
customization buffer, that face appears like this:

     [Hide] Font Lock Comment Face:[sample]
        [State] : STANDARD.
        Font Lock mode face used to highlight comments.
        [ ] Font Family: --
        [ ] Font Foundry: --
        [ ] Width: --
        [ ] Height: --
        [ ] Weight: --
        [ ] Slant: --
        [ ] Underline: --
        [ ] Overline: --
        [ ] Strike-through: --
        [ ] Box around text: --
        [ ] Inverse-video: --
        [X] Foreground: Firebrick     [Choose]  (sample)
        [ ] Background: --
        [ ] Stipple: --
        [ ] Inherit: --
        [Hide Unused Attributes]

The first three lines show the name, `[State]' button, and
documentation for the face.  Below that is a list of "face attributes".
In front of each attribute is a checkbox.  A filled checkbox, `[X]',
means that the face specifies a value for this attribute; an empty
checkbox, `[ ]', means that the face does not specify any special value
for the attribute.  You can activate a checkbox to specify or unspecify
its attribute.

   Most faces only specify a few attributes (in the above example,
`font-lock-comment-face' only specifies the foreground color).  Emacs
has a special face, `default', whose attributes are all specified; it
determines the attributes left unspecified by other faces.

   The `Hide Unused Attributes' button, at the end of the attribute
list, hides the unspecified attributes of the face.  When attributes
are being hidden, the button changes to `[Show All Attributes]', which
reveals the entire attribute list.  The customization buffer may start
out with unspecified attributes hidden, to avoid cluttering the
interface.

   When an attribute is specified, you can change its value in the
usual ways.

   Foreground and background colors can be specified using either color
names or RGB triplets (*note Colors::).  You can also use the
`[Choose]' button to switch to a list of color names; select a color
with <RET> in that buffer to put the color name in the value field.

   Setting, saving and resetting a face work like the same operations
for variables (*note Changing a Variable::).

   A face can specify different appearances for different types of
displays.  For example, a face can make text red on a color display,
but use a bold font on a monochrome display.  To specify multiple
appearances for a face, select `For All Kinds of Displays' in the menu
you get from invoking `[State]'.


File: emacs,  Node: Specific Customization,  Next: Custom Themes,  Prev: Face Customization,  Up: Easy Customization

48.1.6 Customizing Specific Items
---------------------------------

`M-x customize-option <RET> OPTION <RET>'
`M-x customize-variable <RET> OPTION <RET>'
     Set up a customization buffer for just one user option, OPTION.

`M-x customize-face <RET> FACE <RET>'
     Set up a customization buffer for just one face, FACE.

`M-x customize-group <RET> GROUP <RET>'
     Set up a customization buffer for just one group, GROUP.

`M-x customize-apropos <RET> REGEXP <RET>'
     Set up a customization buffer for all the settings and groups that
     match REGEXP.

`M-x customize-changed <RET> VERSION <RET>'
     Set up a customization buffer with all the settings and groups
     whose meaning has changed since Emacs version VERSION.

`M-x customize-saved'
     Set up a customization buffer containing all settings that you
     have saved with customization buffers.

`M-x customize-unsaved'
     Set up a customization buffer containing all settings that you have
     set but not saved.

   If you want to customize a particular user option, type `M-x
customize-option'.  This reads the variable name, and sets up the
customization buffer with just that one user option.  When entering the
variable name into the minibuffer, completion is available, but only
for the names of variables that have been loaded into Emacs.

   Likewise, you can customize a specific face using `M-x
customize-face'.  You can set up a customization buffer for a specific
customization group using `M-x customize-group'.

   `M-x customize-apropos' prompts for a search term--either one or
more words separated by spaces, or a regular expression--and sets up a
customization buffer for all _loaded_ settings and groups with matching
names.  This is like using the search field at the top of the
customization buffer (*note Customization Groups::).

   When you upgrade to a new Emacs version, you might want to consider
customizing new settings, and settings whose meanings or default values
have changed.  To do this, use `M-x customize-changed' and specify a
previous Emacs version number using the minibuffer.  It creates a
customization buffer which shows all the settings and groups whose
definitions have been changed since the specified version, loading them
if necessary.

   If you change settings and then decide the change was a mistake, you
can use two commands to revisit your changes.  Use `M-x
customize-saved' to customize settings that you have saved.  Use `M-x
customize-unsaved' to customize settings that you have set but not
saved.


File: emacs,  Node: Custom Themes,  Next: Creating Custom Themes,  Prev: Specific Customization,  Up: Easy Customization

48.1.7 Custom Themes
--------------------

"Custom themes" are collections of settings that can be enabled or
disabled as a unit.  You can use Custom themes to switch easily between
various collections of settings, and to transfer such collections from
one computer to another.

   A Custom theme is stored an Emacs Lisp source file.  If the name of
the Custom theme is NAME, the theme file is named `NAME-theme.el'.
*Note Creating Custom Themes::, for the format of a theme file and how
to make one.

   Type `M-x customize-themes' to switch to a buffer named `*Custom
Themes*', which lists the Custom themes that Emacs knows about.  By
default, Emacs looks for theme files in two locations: the directory
specified by the variable `custom-theme-directory' (which defaults to
`~/.emacs.d/'), and a directory named `etc/themes' in your Emacs
installation (see the variable `data-directory').  The latter contains
several Custom themes which are distributed with Emacs, which customize
Emacs's faces to fit various color schemes.  (Note, however, that
Custom themes need not be restricted to this purpose; they can be used
to customize variables too).

   If you want Emacs to look for Custom themes in some other directory,
add the directory name to the list variable `custom-theme-load-path'.
Its default value is `(custom-theme-directory t)'; here, the symbol
`custom-theme-directory' has the special meaning of the value of the
variable `custom-theme-directory', while `t' stands for the built-in
theme directory `etc/themes'.  The themes listed in the `*Custom
Themes*' buffer are those found in the directories specified by
`custom-theme-load-path'.

   In the `*Custom Themes*' buffer, you can activate the checkbox next
to a Custom theme to enable or disable the theme for the current Emacs
session.  When a Custom theme is enabled, all of its settings
(variables and faces) take effect in the Emacs session.  To apply the
choice of theme(s) to future Emacs sessions, type `C-x C-s'
(`custom-theme-save') or use the `[Save Theme Settings]' button.

   When you first enable a Custom theme, Emacs displays the contents of
the theme file and asks if you really want to load it.  Because loading
a Custom theme can execute arbitrary Lisp code, you should only say yes
if you know that the theme is safe; in that case, Emacs offers to
remember in the future that the theme is safe (this is done by saving
the theme file's SHA-256 hash to the variable `custom-safe-themes'; if
you want to treat all themes as safe, change its value to `t').  Themes
that come with Emacs (in the `etc/themes' directory) are exempt from
this check, and are always considered safe.

   Setting or saving Custom themes actually works by customizing the
variable `custom-enabled-themes'.  The value of this variable is a list
of Custom theme names (as Lisp symbols, e.g. `tango').  Instead of
using the `*Custom Themes*' buffer to set `custom-enabled-themes', you
can customize the variable using the usual customization interface,
e.g. with `M-x customize-option'.  Note that Custom themes are not
allowed to set `custom-enabled-themes' themselves.

   Any customizations that you make through the customization buffer
take precedence over theme settings.  This lets you easily override
individual theme settings that you disagree with.  If settings from two
different themes overlap, the theme occurring earlier in
`custom-enabled-themes' takes precedence.  In the customization buffer,
if a setting has been changed from its default by a Custom theme, its
`State' display shows `THEMED' instead of `STANDARD'.

   You can enable a specific Custom theme in the current Emacs session
by typing `M-x load-theme'.  This prompts for a theme name, loads the
theme from the theme file, and enables it.  If a theme file has been
loaded before, you can enable the theme without loading its file by
typing `M-x enable-theme'.  To disable a Custom theme, type `M-x
disable-theme'.

   To see a description of a Custom theme, type `?' on its line in the
`*Custom Themes*' buffer; or type `M-x describe-theme' anywhere in
Emacs and enter the theme name.


File: emacs,  Node: Creating Custom Themes,  Prev: Custom Themes,  Up: Easy Customization

48.1.8 Creating Custom Themes
-----------------------------

You can define a Custom theme using an interface similar to the
customization buffer, by typing `M-x customize-create-theme'.  This
switches to a buffer named `*Custom Theme*'.  It also offers to insert
some common Emacs faces into the theme (a convenience, since Custom
themes are often used to customize faces).  If you answer no, the theme
will initially contain no settings.

   Near the top of the `*Custom Theme*' buffer are editable fields
where you can enter the theme's name and description.  The name can be
anything except `user'.  The description is the one that will be shown
when you invoke `M-x describe-theme' for the theme.  Its first line
should be a brief one-sentence summary; in the buffer made by `M-x
customize-themes', this sentence is displayed next to the theme name.

   To add a new setting to the theme, use the `[Insert Additional
Face]' or `[Insert Additional Variable]' buttons.  Each button reads a
face or variable name using the minibuffer, with completion, and
inserts a customization entry for the face or variable.  You can edit
the variable values or face attributes in the same way as in a normal
customization buffer.  To remove a face or variable from the theme,
uncheck the checkbox next to its name.

   After specifying the Custom theme's faces and variables, type `C-x
C-s' (`custom-theme-write') or use the buffer's `[Save Theme]' button.
This saves the theme file, named `NAME-theme.el' where NAME is the
theme name, in the directory named by `custom-theme-directory'.

   From the `*Custom Theme*' buffer, you can view and edit an existing
Custom theme by activating the `[Visit Theme]' button and specifying
the theme name.  You can also add the settings of another theme into
the buffer, using the `[Merge Theme]' button.  You can import your
non-theme settings into a Custom theme by using the `[Merge Theme]'
button and specifying the special theme named `user'.

   A theme file is simply an Emacs Lisp source file, and loading the
Custom theme works by loading the Lisp file.  Therefore, you can edit a
theme file directly instead of using the `*Custom Theme*' buffer.
*Note Custom Themes: (elisp)Custom Themes, for details.


File: emacs,  Node: Variables,  Next: Key Bindings,  Prev: Easy Customization,  Up: Customization

48.2 Variables
==============

A "variable" is a Lisp symbol which has a value.  The symbol's name is
also called the "variable name".  A variable name can contain any
characters that can appear in a file, but most variable names consist
of ordinary words separated by hyphens.

   The name of the variable serves as a compact description of its
role.  Most variables also have a "documentation string", which
describes what the variable's purpose is, what kind of value it should
have, and how the value will be used.  You can view this documentation
using the help command `C-h v' (`describe-variable').  *Note
Examining::.

   Emacs uses many Lisp variables for internal record keeping, but the
most interesting variables for a non-programmer user are those meant
for users to change--these are called "customizable variables" or "user
options" (*note Easy Customization::).  In the following sections, we
will describe other aspects of Emacs variables, such as how to set them
outside Customize.

   Emacs Lisp allows any variable (with a few exceptions) to have any
kind of value.  However, many variables are meaningful only if assigned
values of a certain type.  For example, only numbers are meaningful
values for `kill-ring-max', which specifies the maximum length of the
kill ring (*note Earlier Kills::); if you give `kill-ring-max' a string
value, commands such as `C-y' (`yank') will signal an error.  On the
other hand, some variables don't care about type; for instance, if a
variable has one effect for `nil' values and another effect for
"non-`nil'" values, then any value that is not the symbol `nil' induces
the second effect, regardless of its type (by convention, we usually
use the value `t'--a symbol which stands for "true"--to specify a
non-`nil' value).  If you set a variable using the customization
buffer, you need not worry about giving it an invalid type: the
customization buffer usually only allows you to enter meaningful
values.  When in doubt, use `C-h v' (`describe-variable') to check the
variable's documentation string to see kind of value it expects (*note
Examining::).

* Menu:

* Examining::           Examining or setting one variable's value.
* Hooks::               Hook variables let you specify programs for parts
                          of Emacs to run on particular occasions.
* Locals::              Per-buffer values of variables.
* File Variables::      How files can specify variable values.
* Directory Variables:: How variable values can be specified by directory.


File: emacs,  Node: Examining,  Next: Hooks,  Up: Variables

48.2.1 Examining and Setting Variables
--------------------------------------

`C-h v VAR <RET>'
     Display the value and documentation of variable VAR
     (`describe-variable').

`M-x set-variable <RET> VAR <RET> VALUE <RET>'
     Change the value of variable VAR to VALUE.

   To examine the value of a variable, use `C-h v'
(`describe-variable').  This reads a variable name using the
minibuffer, with completion, and displays both the value and the
documentation of the variable.  For example,

     C-h v fill-column <RET>

displays something like this:

     fill-column is a variable defined in `C source code'.
     fill-column's value is 70

     Automatically becomes buffer-local when set in any fashion.
     This variable is safe as a file local variable if its value
     satisfies the predicate `integerp'.

     Documentation:
     Column beyond which automatic line-wrapping should happen.
     Interactively, you can set the local value with C-x f.

     You can customize this variable.

The line that says "You can customize the variable" indicates that this
variable is a user option.  `C-h v' is not restricted to user options;
it allows non-customizable variables too.

   The most convenient way to set a specific customizable variable is
with `M-x set-variable'.  This reads the variable name with the
minibuffer (with completion), and then reads a Lisp expression for the
new value using the minibuffer a second time (you can insert the old
value into the minibuffer for editing via `M-n').  For example,

     M-x set-variable <RET> fill-column <RET> 75 <RET>

sets `fill-column' to 75.

   `M-x set-variable' is limited to customizable variables, but you can
set any variable with a Lisp expression like this:

     (setq fill-column 75)

To execute such an expression, type `M-:' (`eval-expression') and enter
the expression in the minibuffer (*note Lisp Eval::).  Alternatively,
go to the `*scratch*' buffer, type in the expression, and then type
`C-j' (*note Lisp Interaction::).

   Setting variables, like all means of customizing Emacs except where
otherwise stated, affects only the current Emacs session.  The only way
to alter the variable in future sessions is to put something in your
initialization file (*note Init File::).


File: emacs,  Node: Hooks,  Next: Locals,  Prev: Examining,  Up: Variables

48.2.2 Hooks
------------

"Hooks" are an important mechanism for customizing Emacs.  A hook is a
Lisp variable which holds a list of functions, to be called on some
well-defined occasion.  (This is called "running the hook".)  The
individual functions in the list are called the "hook functions" of the
hook.  For example, the hook `kill-emacs-hook' runs just before exiting
Emacs (*note Exiting::).

   Most hooks are "normal hooks".  This means that when Emacs runs the
hook, it calls each hook function in turn, with no arguments.  We have
made an effort to keep most hooks normal, so that you can use them in a
uniform way.  Every variable whose name ends in `-hook' is a normal
hook.

   A few hooks are "abnormal hooks".  Their names end in `-hooks' or
`-functions', instead of `-hook'.  What makes these hooks abnormal is
the way its functions are called--perhaps they are given arguments, or
perhaps the values they return are used in some way.  For example,
`find-file-not-found-functions' is abnormal because as soon as one hook
function returns a non-`nil' value, the rest are not called at all
(*note Visiting::).  The documentation of each abnormal hook variable
explains how its functions are used.

   You can set a hook variable with `setq' like any other Lisp
variable, but the recommended way to add a function to a hook (either
normal or abnormal) is to use `add-hook', as shown by the following
examples.  *Note Hooks: (elisp)Hooks, for details.

   Most major modes run one or more "mode hooks" as the last step of
initialization.  Mode hooks are a convenient way to customize the
behavior of individual modes; they are always normal.  For example,
here's how to set up a hook to turn on Auto Fill mode in Text mode and
other modes based on Text mode:

     (add-hook 'text-mode-hook 'auto-fill-mode)

This works by calling `auto-fill-mode', which enables the minor mode
when no argument is supplied (*note Minor Modes::).  Next, suppose you
don't want Auto Fill mode turned on in LaTeX mode, which is one of the
modes based on Text mode.  You can do this with the following
additional line:

     (add-hook 'latex-mode-hook (lambda () (auto-fill-mode -1)))

Here we have used the special macro `lambda' to construct an anonymous
function (*note Lambda Expressions: (elisp)Lambda Expressions.), which
calls `auto-fill-mode' with an argument of `-1' to disable the minor
mode.  Because LaTeX mode runs `latex-mode-hook' after running
`text-mode-hook', the result leaves Auto Fill mode disabled.

   Here is a more complex example, showing how to use a hook to
customize the indentation of C code:

     (setq my-c-style
       '((c-comment-only-line-offset . 4)
         (c-cleanup-list . (scope-operator
                            empty-defun-braces
                            defun-close-semi))))

     (add-hook 'c-mode-common-hook
       (lambda () (c-add-style "my-style" my-c-style t)))

   Major mode hooks also apply to other major modes "derived" from the
original mode (*note Derived Modes: (elisp)Derived Modes.).  For
instance, HTML mode is derived from Text mode (*note HTML Mode::); when
HTML mode is enabled, it runs `text-mode-hook' before running
`html-mode-hook'.  This provides a convenient way to use a single hook
to affect several related modes.  In particular, if you want to apply a
hook function to any programming language mode, add it to
`prog-mode-hook'; Prog mode is a major mode that does little else than
to let other major modes inherit from it, exactly for this purpose.

   It is best to design your hook functions so that the order in which
they are executed does not matter.  Any dependence on the order is
asking for trouble.  However, the order is predictable: the hook
functions are executed in the order they appear in the hook.

   If you play with adding various different versions of a hook
function by calling `add-hook' over and over, remember that all the
versions you added will remain in the hook variable together.  You can
clear out individual functions by calling `remove-hook', or do `(setq
HOOK-VARIABLE nil)' to remove everything.

   If the hook variable is buffer-local, the buffer-local variable will
be used instead of the global variable.  However, if the buffer-local
variable contains the element `t', the global hook variable will be run
as well.


File: emacs,  Node: Locals,  Next: File Variables,  Prev: Hooks,  Up: Variables

48.2.3 Local Variables
----------------------

`M-x make-local-variable <RET> VAR <RET>'
     Make variable VAR have a local value in the current buffer.

`M-x kill-local-variable <RET> VAR <RET>'
     Make variable VAR use its global value in the current buffer.

`M-x make-variable-buffer-local <RET> VAR <RET>'
     Mark variable VAR so that setting it will make it local to the
     buffer that is current at that time.

   Almost any variable can be made "local" to a specific Emacs buffer.
This means that its value in that buffer is independent of its value in
other buffers.  A few variables are always local in every buffer.
Every other Emacs variable has a "global" value which is in effect in
all buffers that have not made the variable local.

   `M-x make-local-variable' reads the name of a variable and makes it
local to the current buffer.  Changing its value subsequently in this
buffer will not affect others, and changes in its global value will not
affect this buffer.

   `M-x make-variable-buffer-local' marks a variable so it will become
local automatically whenever it is set.  More precisely, once a
variable has been marked in this way, the usual ways of setting the
variable automatically do `make-local-variable' first.  We call such
variables "per-buffer" variables.  Many variables in Emacs are normally
per-buffer; the variable's document string tells you when this is so.
A per-buffer variable's global value is normally never effective in any
buffer, but it still has a meaning: it is the initial value of the
variable for each new buffer.

   Major modes (*note Major Modes::) always make variables local to the
buffer before setting the variables.  This is why changing major modes
in one buffer has no effect on other buffers.  Minor modes also work by
setting variables--normally, each minor mode has one controlling
variable which is non-`nil' when the mode is enabled (*note Minor
Modes::).  For many minor modes, the controlling variable is per
buffer, and thus always buffer-local.  Otherwise, you can make it local
in a specific buffer like any other variable.

   A few variables cannot be local to a buffer because they are always
local to each display instead (*note Multiple Displays::).  If you try
to make one of these variables buffer-local, you'll get an error
message.

   `M-x kill-local-variable' makes a specified variable cease to be
local to the current buffer.  The global value of the variable
henceforth is in effect in this buffer.  Setting the major mode kills
all the local variables of the buffer except for a few variables
specially marked as "permanent locals".

   To set the global value of a variable, regardless of whether the
variable has a local value in the current buffer, you can use the Lisp
construct `setq-default'.  This construct is used just like `setq', but
it sets variables' global values instead of their local values (if
any).  When the current buffer does have a local value, the new global
value may not be visible until you switch to another buffer.  Here is
an example:

     (setq-default fill-column 75)

`setq-default' is the only way to set the global value of a variable
that has been marked with `make-variable-buffer-local'.

   Lisp programs can use `default-value' to look at a variable's
default value.  This function takes a symbol as argument and returns its
default value.  The argument is evaluated; usually you must quote it
explicitly.  For example, here's how to obtain the default value of
`fill-column':

     (default-value 'fill-column)


File: emacs,  Node: File Variables,  Next: Directory Variables,  Prev: Locals,  Up: Variables

48.2.4 Local Variables in Files
-------------------------------

A file can specify local variable values to use when editing the file
with Emacs.  Visiting the file checks for local variable
specifications; it automatically makes these variables local to the
buffer, and sets them to the values specified in the file.

* Menu:

* Specifying File Variables:: Specifying file local variables.
* Safe File Variables::       Making sure file local variables are safe.


File: emacs,  Node: Specifying File Variables,  Next: Safe File Variables,  Up: File Variables

48.2.4.1 Specifying File Variables
..................................

There are two ways to specify file local variable values: in the first
line, or with a local variables list.  Here's how to specify them in the
first line:

     -*- mode: MODENAME; VAR: VALUE; ... -*-

You can specify any number of variable/value pairs in this way, each
pair with a colon and semicolon.  The special variable/value pair
`mode: MODENAME;', if present, specifies a major mode.  The VALUEs are
used literally, and not evaluated.

   You can use `M-x add-file-local-variable-prop-line' instead of
adding entries by hand.  This command prompts for a variable and value,
and adds them to the first line in the appropriate way.  `M-x
delete-file-local-variable-prop-line' prompts for a variable, and
deletes its entry from the line.  The command `M-x
copy-dir-locals-to-file-locals-prop-line' copies the current
directory-local variables to the first line (*note Directory
Variables::).

   Here is an example first line that specifies Lisp mode and sets two
variables with numeric values:

     ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-

Aside from `mode', other keywords that have special meanings as file
variables are `coding', `unibyte', and `eval'.  These are described
below.

   In shell scripts, the first line is used to identify the script
interpreter, so you cannot put any local variables there.  To
accommodate this, Emacs looks for local variable specifications in the
_second_ line if the first line specifies an interpreter.  The same is
true for man pages which start with the magic string `'\"' to specify a
list of troff preprocessors (not all do, however).

   Apart from using a `-*-' line, you can define file local variables
using a "local variables list" near the end of the file.  The start of
the local variables list should be no more than 3000 characters from
the end of the file, and must be on the last page if the file is
divided into pages.

   If a file has both a local variables list and a `-*-' line, Emacs
processes _everything_ in the `-*-' line first, and _everything_ in the
local variables list afterward.  The exception to this is a major mode
specification.  Emacs applies this first, wherever it appears, since
most major modes kill all local variables as part of their
initialization.

   A local variables list starts with a line containing the string
`Local Variables:', and ends with a line containing the string `End:'.
In between come the variable names and values, one set per line, like
this:

     /* Local Variables:  */
     /* mode: c           */
     /* comment-column: 0 */
     /* End:              */

In this example, each line starts with the prefix `/*' and ends with
the suffix `*/'.  Emacs recognizes the prefix and suffix by finding
them surrounding the magic string `Local Variables:', on the first line
of the list; it then automatically discards them from the other lines
of the list.  The usual reason for using a prefix and/or suffix is to
embed the local variables list in a comment, so it won't confuse other
programs that the file is intended for.  The example above is for the C
programming language, where comments start with `/*' and end with `*/'.

   Instead of typing in the local variables list directly, you can use
the command `M-x add-file-local-variable'.  This prompts for a variable
and value, and adds them to the list, adding the `Local Variables:'
string and start and end markers as necessary.  The command `M-x
delete-file-local-variable' deletes a variable from the list.  `M-x
copy-dir-locals-to-file-locals' copies directory-local variables to the
list (*note Directory Variables::).

   As with the `-*-' line, the variables in a local variables list are
used literally, and are not evaluated first.  If you want to split a
long string value across multiple lines of the file, you can use
backslash-newline, which is ignored in Lisp string constants; you
should put the prefix and suffix on each line, even lines that start or
end within the string, as they will be stripped off when processing the
list.  Here is an example:

     # Local Variables:
     # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
     #   -Dmumble=blaah"
     # End:

   Some "variable names" have special meanings in a local variables
list:

   * `mode' enables the specified major mode.

   * `eval' evaluates the specified Lisp expression (the value returned
     by that expression is ignored).

   * `coding' specifies the coding system for character code conversion
     of this file.  *Note Coding Systems::.

   * `unibyte' says to load or compile a file of Emacs Lisp in unibyte
     mode, if the value is `t'.  *Note Disabling Multibyte::.

These four keywords are not really variables; setting them in any other
context has no special meaning.

   Do not use the `mode' keyword for minor modes.  To enable or disable
a minor mode in a local variables list, use the `eval' keyword with a
Lisp expression that runs the mode command (*note Minor Modes::).  For
example, the following local variables list enables Eldoc mode (*note
Lisp Doc::) by calling `eldoc-mode' with no argument (calling it with
an argument of 1 would do the same), and disables Font Lock mode (*note
Font Lock::) by calling `font-lock-mode' with an argument of -1.

     ;; Local Variables:
     ;; eval: (eldoc-mode)
     ;; eval: (font-lock-mode -1)
     ;; End:

Note, however, that it is often a mistake to specify minor modes this
way.  Minor modes represent individual user preferences, and it may be
inappropriate to impose your preferences on another user who might edit
the file.  If you wish to automatically enable or disable a minor mode
in a situation-dependent way, it is often better to do it in a major
mode hook (*note Hooks::).

   Use the command `M-x normal-mode' to reset the local variables and
major mode of a buffer according to the file name and contents,
including the local variables list if any.  *Note Choosing Modes::.


File: emacs,  Node: Safe File Variables,  Prev: Specifying File Variables,  Up: File Variables

48.2.4.2 Safety of File Variables
.................................

File-local variables can be dangerous; when you visit someone else's
file, there's no telling what its local variables list could do to your
Emacs.  Improper values of the `eval' "variable", and other variables
such as `load-path', could execute Lisp code you didn't intend to run.

   Therefore, whenever Emacs encounters file local variable values that
are not known to be safe, it displays the file's entire local variables
list, and asks you for confirmation before setting them.  You can type
`y' or <SPC> to put the local variables list into effect, or `n' to
ignore it.  When Emacs is run in batch mode (*note Initial Options::),
it can't really ask you, so it assumes the answer `n'.

   Emacs normally recognizes certain variable/value pairs as safe.  For
instance, it is safe to give `comment-column' or `fill-column' any
integer value.  If a file specifies only known-safe variable/value
pairs, Emacs does not ask for confirmation before setting them.
Otherwise, you can tell Emacs to record all the variable/value pairs in
this file as safe, by typing `!' at the confirmation prompt.  When
Emacs encounters these variable/value pairs subsequently, in the same
file or others, it will assume they are safe.

   Some variables, such as `load-path', are considered particularly
"risky": there is seldom any reason to specify them as local variables,
and changing them can be dangerous.  If a file contains only risky
local variables, Emacs neither offers nor accepts `!' as input at the
confirmation prompt.  If some of the local variables in a file are
risky, and some are only potentially unsafe, you can enter `!' at the
prompt.  It applies all the variables, but only marks the non-risky
ones as safe for the future.  If you really want to record safe values
for risky variables, do it directly by customizing
`safe-local-variable-values' (*note Easy Customization::).

   The variable `enable-local-variables' allows you to change the way
Emacs processes local variables.  Its default value is `t', which
specifies the behavior described above.  If it is `nil', Emacs simply
ignores all file local variables.  `:safe' means use only the safe
values and ignore the rest.  Any other value says to query you about
each file that has local variables, without trying to determine whether
the values are known to be safe.

   The variable `enable-local-eval' controls whether Emacs processes
`eval' variables.  The three possibilities for the variable's value are
`t', `nil', and anything else, just as for `enable-local-variables'.
The default is `maybe', which is neither `t' nor `nil', so normally
Emacs does ask for confirmation about processing `eval' variables.

   As an exception, Emacs never asks for confirmation to evaluate any
`eval' form if that form occurs within the variable
`safe-local-eval-forms'.


File: emacs,  Node: Directory Variables,  Prev: File Variables,  Up: Variables

48.2.5 Per-Directory Local Variables
------------------------------------

Sometimes, you may wish to define the same set of local variables to
all the files in a certain directory and its subdirectories, such as
the directory tree of a large software project.  This can be
accomplished with "directory-local variables".

   The usual way to define directory-local variables is to put a file
named `.dir-locals.el'(1) in a directory.  Whenever Emacs visits any
file in that directory or any of its subdirectories, it will apply the
directory-local variables specified in `.dir-locals.el', as though they
had been defined as file-local variables for that file (*note File
Variables::).  Emacs searches for `.dir-locals.el' starting in the
directory of the visited file, and moving up the directory tree.  To
avoid slowdown, this search is skipped for remote files.

   The `.dir-locals.el' file should hold a specially-constructed list,
which maps major mode names (symbols) to alists (*note Association
Lists: (elisp)Association Lists.).  Each alist entry consists of a
variable name and the directory-local value to assign to that variable,
when the specified major mode is enabled.  Instead of a mode name, you
can specify `nil', which means that the alist applies to any mode; or
you can specify a subdirectory name (a string), in which case the alist
applies to all files in that subdirectory.

   Here's an example of a `.dir-locals.el' file:

     ((nil . ((indent-tabs-mode . t)
              (fill-column . 80)))
      (c-mode . ((c-file-style . "BSD")))
                 (subdirs . nil)))
      ("src/imported"
       . ((nil . ((change-log-default-name
                   . "ChangeLog.local"))))))

This sets `indent-tabs-mode' and `fill-column' for any file in the
directory tree, and the indentation style for any C source file.  The
special `subdirs' element is not a variable, but a special keyword
which indicates that the C mode settings are only to be applied in the
current directory, not in any subdirectories.  Finally, it specifies a
different `ChangeLog' file name for any file in the `src/imported'
subdirectory.

   Instead of editing the `.dir-locals.el' file by hand, you can use
the command `M-x add-dir-local-variable'.  This prompts for a mode or
subdirectory name, and for variable and value, and adds the entry
defining the directory-local variable.  `M-x delete-dir-local-variable'
deletes an entry.  `M-x copy-file-locals-to-dir-locals' copies the
file-local variables in the current file into `.dir-locals.el'.

   Another method of specifying directory-local variables is to define
a group of variables/value pairs in a "directory class", using the
`dir-locals-set-class-variables' function; then, tell Emacs which
directories correspond to the class by using the
`dir-locals-set-directory-class' function.  These function calls
normally go in your initialization file (*note Init File::).  This
method is useful when you can't put `.dir-locals.el' in a directory for
some reason.  For example, you could apply settings to an unwritable
directory this way:

     (dir-locals-set-class-variables 'unwritable-directory
        '((nil . ((some-useful-setting . value)))))

     (dir-locals-set-directory-class
        "/usr/include/" 'unwritable-directory)

   If a variable has both a directory-local and file-local value
specified, the file-local value takes effect.  Unsafe directory-local
variables are handled in the same way as unsafe file-local variables
(*note Safe File Variables::).

   Directory-local variables also take effect in certain buffers that
do not visit a file directly but perform work within a directory, such
as Dired buffers (*note Dired::).

   ---------- Footnotes ----------

   (1)  On MS-DOS, the name of this file should be `_dir-locals.el',
due to limitations of the DOS filesystems.  If the filesystem is
limited to 8+3 file names, the name of the file will be truncated by
the OS to `_dir-loc.el'.


File: emacs,  Node: Key Bindings,  Next: Init File,  Prev: Variables,  Up: Customization

48.3 Customizing Key Bindings
=============================

This section describes "key bindings", which map keys to commands, and
"keymaps", which record key bindings.  It also explains how to
customize key bindings, which is done by editing your init file (*note
Init Rebinding::).

* Menu:

* Keymaps::             Generalities.  The global keymap.
* Prefix Keymaps::      Keymaps for prefix keys.
* Local Keymaps::       Major and minor modes have their own keymaps.
* Minibuffer Maps::     The minibuffer uses its own local keymaps.
* Rebinding::           How to redefine one key's meaning conveniently.
* Init Rebinding::      Rebinding keys with your initialization file.
* Modifier Keys::       Using modifier keys in key bindings.
* Function Keys::       Rebinding terminal function keys.
* Named ASCII Chars::   Distinguishing <TAB> from C-i, and so on.
* Mouse Buttons::       Rebinding mouse buttons in Emacs.
* Disabling::           Disabling a command means confirmation is required
                          before it can be executed.  This is done to protect
                          beginners from surprises.


File: emacs,  Node: Keymaps,  Next: Prefix Keymaps,  Up: Key Bindings

48.3.1 Keymaps
--------------

As described in *note Commands::, each Emacs command is a Lisp function
whose definition provides for interactive use.  Like every Lisp
function, a command has a function name, which usually consists of
lower-case letters and hyphens.

   A "key sequence" ("key", for short) is a sequence of "input events"
that have a meaning as a unit.  Input events include characters,
function keys and mouse buttons--all the inputs that you can send to
the computer.  A key sequence gets its meaning from its "binding",
which says what command it runs.

   The bindings between key sequences and command functions are
recorded in data structures called "keymaps".  Emacs has many of these,
each used on particular occasions.

   The "global" keymap is the most important keymap because it is
always in effect.  The global keymap defines keys for Fundamental mode
(*note Major Modes::); most of these definitions are common to most or
all major modes.  Each major or minor mode can have its own keymap
which overrides the global definitions of some keys.

   For example, a self-inserting character such as `g' is
self-inserting because the global keymap binds it to the command
`self-insert-command'.  The standard Emacs editing characters such as
`C-a' also get their standard meanings from the global keymap.
Commands to rebind keys, such as `M-x global-set-key', work by storing
the new binding in the proper place in the global map (*note
Rebinding::).

   Most modern keyboards have function keys as well as character keys.
Function keys send input events just as character keys do, and keymaps
can have bindings for them.  Key sequences can mix function keys and
characters.  For example, if your keyboard has a <Home> function key,
Emacs can recognize key sequences like `C-x <Home>'.  You can even mix
mouse events with keyboard events, such as `S-down-mouse-1'.

   On text terminals, typing a function key actually sends the computer
a sequence of characters; the precise details of the sequence depends
on the function key and on the terminal type.  (Often the sequence
starts with `<ESC> ['.)  If Emacs understands your terminal type
properly, it automatically handles such sequences as single input
events.


File: emacs,  Node: Prefix Keymaps,  Next: Local Keymaps,  Prev: Keymaps,  Up: Key Bindings

48.3.2 Prefix Keymaps
---------------------

Internally, Emacs records only single events in each keymap.
Interpreting a key sequence of multiple events involves a chain of
keymaps: the first keymap gives a definition for the first event, which
is another keymap, which is used to look up the second event in the
sequence, and so on.  Thus, a prefix key such as `C-x' or <ESC> has its
own keymap, which holds the definition for the event that immediately
follows that prefix.

   The definition of a prefix key is usually the keymap to use for
looking up the following event.  The definition can also be a Lisp
symbol whose function definition is the following keymap; the effect is
the same, but it provides a command name for the prefix key that can be
used as a description of what the prefix key is for.  Thus, the binding
of `C-x' is the symbol `Control-X-prefix', whose function definition is
the keymap for `C-x' commands.  The definitions of `C-c', `C-x', `C-h'
and <ESC> as prefix keys appear in the global map, so these prefix keys
are always available.

   Aside from ordinary prefix keys, there is a fictitious "prefix key"
which represents the menu bar; see *note Menu Bar: (elisp)Menu Bar, for
special information about menu bar key bindings.  Mouse button events
that invoke pop-up menus are also prefix keys; see *note Menu Keymaps:
(elisp)Menu Keymaps, for more details.

   Some prefix keymaps are stored in variables with names:

   * `ctl-x-map' is the variable name for the map used for characters
     that follow `C-x'.

   * `help-map' is for characters that follow `C-h'.

   * `esc-map' is for characters that follow <ESC>.  Thus, all Meta
     characters are actually defined by this map.

   * `ctl-x-4-map' is for characters that follow `C-x 4'.

   * `mode-specific-map' is for characters that follow `C-c'.


File: emacs,  Node: Local Keymaps,  Next: Minibuffer Maps,  Prev: Prefix Keymaps,  Up: Key Bindings

48.3.3 Local Keymaps
--------------------

So far, we have explained the ins and outs of the global map.  Major
modes customize Emacs by providing their own key bindings in "local
keymaps".  For example, C mode overrides <TAB> to make it indent the
current line for C code.  Minor modes can also have local keymaps;
whenever a minor mode is in effect, the definitions in its keymap
override both the major mode's local keymap and the global keymap.  In
addition, portions of text in the buffer can specify their own keymaps,
which override all other keymaps.

   A local keymap can redefine a key as a prefix key by defining it as
a prefix keymap.  If the key is also defined globally as a prefix, its
local and global definitions (both keymaps) effectively combine: both
definitions are used to look up the event that follows the prefix key.
For example, if a local keymap defines `C-c' as a prefix keymap, and
that keymap defines `C-z' as a command, this provides a local meaning
for `C-c C-z'.  This does not affect other sequences that start with
`C-c'; if those sequences don't have their own local bindings, their
global bindings remain in effect.

   Another way to think of this is that Emacs handles a multi-event key
sequence by looking in several keymaps, one by one, for a binding of the
whole key sequence.  First it checks the minor mode keymaps for minor
modes that are enabled, then it checks the major mode's keymap, and then
it checks the global keymap.  This is not precisely how key lookup
works, but it's good enough for understanding the results in ordinary
circumstances.


File: emacs,  Node: Minibuffer Maps,  Next: Rebinding,  Prev: Local Keymaps,  Up: Key Bindings

48.3.4 Minibuffer Keymaps
-------------------------

The minibuffer has its own set of local keymaps; they contain various
completion and exit commands.

   * `minibuffer-local-map' is used for ordinary input (no completion).

   * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
     like <RET>.

   * `minibuffer-local-completion-map' is for permissive completion.

   * `minibuffer-local-must-match-map' is for strict completion and for
     cautious completion.

   * `minibuffer-local-filename-completion-map' and
     `minibuffer-local-filename-must-match-map' are like the two
     previous ones, but they are specifically for file name completion.
     They do not bind <SPC>.


File: emacs,  Node: Rebinding,  Next: Init Rebinding,  Prev: Minibuffer Maps,  Up: Key Bindings

48.3.5 Changing Key Bindings Interactively
------------------------------------------

The way to redefine an Emacs key is to change its entry in a keymap.
You can change the global keymap, in which case the change is effective
in all major modes (except those that have their own overriding local
bindings for the same key).  Or you can change a local keymap, which
affects all buffers using the same major mode.

   In this section, we describe how to rebind keys for the present
Emacs session.  *Note Init Rebinding::, for a description of how to
make key rebindings affect future Emacs sessions.

`M-x global-set-key <RET> KEY CMD <RET>'
     Define KEY globally to run CMD.

`M-x local-set-key <RET> KEY CMD <RET>'
     Define KEY locally (in the major mode now in effect) to run CMD.

`M-x global-unset-key <RET> KEY'
     Make KEY undefined in the global map.

`M-x local-unset-key <RET> KEY'
     Make KEY undefined locally (in the major mode now in effect).

   For example, the following binds `C-z' to the `shell' command (*note
Interactive Shell::), replacing the normal global definition of `C-z':

     M-x global-set-key <RET> C-z shell <RET>

The `global-set-key' command reads the command name after the key.
After you press the key, a message like this appears so that you can
confirm that you are binding the key you want:

     Set key C-z to command:

   You can redefine function keys and mouse events in the same way; just
type the function key or click the mouse when it's time to specify the
key to rebind.

   You can rebind a key that contains more than one event in the same
way.  Emacs keeps reading the key to rebind until it is a complete key
(that is, not a prefix key).  Thus, if you type `C-f' for KEY, that's
the end; it enters the minibuffer immediately to read CMD.  But if you
type `C-x', since that's a prefix, it reads another character; if that
is `4', another prefix character, it reads one more character, and so
on.  For example,

     M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>

redefines `C-x 4 $' to run the (fictitious) command
`spell-other-window'.

   You can remove the global definition of a key with
`global-unset-key'.  This makes the key "undefined"; if you type it,
Emacs will just beep.  Similarly, `local-unset-key' makes a key
undefined in the current major mode keymap, which makes the global
definition (or lack of one) come back into effect in that major mode.

   If you have redefined (or undefined) a key and you subsequently wish
to retract the change, undefining the key will not do the job--you need
to redefine the key with its standard definition.  To find the name of
the standard definition of a key, go to a Fundamental mode buffer in a
fresh Emacs and use `C-h c'.  The documentation of keys in this manual
also lists their command names.

   If you want to prevent yourself from invoking a command by mistake,
it is better to disable the command than to undefine the key.  A
disabled command is less work to invoke when you really want to.  *Note
Disabling::.


File: emacs,  Node: Init Rebinding,  Next: Modifier Keys,  Prev: Rebinding,  Up: Key Bindings

48.3.6 Rebinding Keys in Your Init File
---------------------------------------

If you have a set of key bindings that you like to use all the time,
you can specify them in your initialization file by writing Lisp code.
*Note Init File::, for a description of the initialization file.

   There are several ways to write a key binding using Lisp.  The
simplest is to use the `kbd' macro, which converts a textual
representation of a key sequence--similar to how we have written key
sequences in this manual--into a form that can be passed as an argument
to `global-set-key'.  For example, here's how to bind `C-z' to the
`shell' command (*note Interactive Shell::):

     (global-set-key (kbd "C-z") 'shell)

The single-quote before the command name, `shell', marks it as a
constant symbol rather than a variable.  If you omit the quote, Emacs
would try to evaluate `shell' as a variable.  This probably causes an
error; it certainly isn't what you want.

   Here are some additional examples, including binding function keys
and mouse events:

     (global-set-key (kbd "C-c y") 'clipboard-yank)
     (global-set-key (kbd "C-M-q") 'query-replace)
     (global-set-key (kbd "<f5>") 'flyspell-mode)
     (global-set-key (kbd "C-<f5>") 'linum-mode)
     (global-set-key (kbd "C-<right>") 'forward-sentence)
     (global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)

   Instead of using the `kbd' macro, you can use a Lisp string or
vector to specify the key sequence.  Using a string is simpler, but
only works for ASCII characters and Meta-modified ASCII characters.
For example, here's how to bind `C-x M-l' to `make-symbolic-link'
(*note Misc File Ops::):

     (global-set-key "\C-x\M-l" 'make-symbolic-link)

   To put <TAB>, <RET>, <ESC>, or <DEL> in the string, use the Emacs
Lisp escape sequences `\t', `\r', `\e', and `\d' respectively.  Here is
an example which binds `C-x <TAB>' to `indent-rigidly' (*note
Indentation::):

     (global-set-key "\C-x\t" 'indent-rigidly)

   When the key sequence includes function keys or mouse button events,
or non-ASCII characters such as `C-=' or `H-a', you can use a vector to
specify the key sequence.  Each element in the vector stands for an
input event; the elements are separated by spaces and surrounded by a
pair of square brackets.  If a vector element is a character, write it
as a Lisp character constant: `?' followed by the character as it would
appear in a string.  Function keys are represented by symbols (*note
Function Keys::); simply write the symbol's name, with no other
delimiters or punctuation.  Here are some examples:

     (global-set-key [?\C-=] 'make-symbolic-link)
     (global-set-key [?\M-\C-=] 'make-symbolic-link)
     (global-set-key [?\H-a] 'make-symbolic-link)
     (global-set-key [f7] 'make-symbolic-link)
     (global-set-key [C-mouse-1] 'make-symbolic-link)

You can use a vector for the simple cases too:

     (global-set-key [?\C-z ?\M-l] 'make-symbolic-link)

   Language and coding systems may cause problems with key bindings for
non-ASCII characters.  *Note Init Non-ASCII::.

   As described in *note Local Keymaps::, major modes and minor modes
can define local keymaps.  These keymaps are constructed when the mode
is used for the first time in a session.  If you wish to change one of
these keymaps, you must use the "mode hook" (*note Hooks::).

   For example, Texinfo mode runs the hook `texinfo-mode-hook'.  Here's
how you can use the hook to add local bindings for `C-c n' and `C-c p'
in Texinfo mode:

     (add-hook 'texinfo-mode-hook
               '(lambda ()
                  (define-key texinfo-mode-map "\C-cp"
                              'backward-paragraph)
                  (define-key texinfo-mode-map "\C-cn"
                              'forward-paragraph)))


File: emacs,  Node: Modifier Keys,  Next: Function Keys,  Prev: Init Rebinding,  Up: Key Bindings

48.3.7 Modifier Keys
--------------------

The default key bindings in Emacs are set up so that modified
alphabetical characters are case-insensitive.  In other words, `C-A'
does the same thing as `C-a', and `M-A' does the same thing as `M-a'.
This concerns only alphabetical characters, and does not apply to
"shifted" versions of other keys; for instance, `C-@' is not the same
as `C-2'.

   A <Control>-modified alphabetical character is always considered
case-insensitive: Emacs always treats `C-A' as `C-a', `C-B' as `C-b',
and so forth.  The reason for this is historical.

   For all other modifiers, you can make the modified alphabetical
characters case-sensitive when you customize Emacs.  For instance, you
could make `M-a' and `M-A' run different commands.

   Although only the <Control> and <Meta> modifier keys are commonly
used, Emacs supports three other modifier keys.  These are called
<Super>, <Hyper> and <Alt>.  Few terminals provide ways to use these
modifiers; the key labeled <Alt> on most keyboards usually issues the
<Meta> modifier, not <Alt>.  The standard key bindings in Emacs do not
include any characters with these modifiers.  However, you can
customize Emacs to assign meanings to them.  The modifier bits are
labeled as `s-', `H-' and `A-' respectively.

   Even if your keyboard lacks these additional modifier keys, you can
enter it using `C-x @': `C-x @ h' adds the "hyper" flag to the next
character, `C-x @ s' adds the "super" flag, and `C-x @ a' adds the
"alt" flag.  For instance, `C-x @ h C-a' is a way to enter
`Hyper-Control-a'.  (Unfortunately, there is no way to add two
modifiers by using `C-x @' twice for the same character, because the
first one goes to work on the `C-x'.)


File: emacs,  Node: Function Keys,  Next: Named ASCII Chars,  Prev: Modifier Keys,  Up: Key Bindings

48.3.8 Rebinding Function Keys
------------------------------

Key sequences can contain function keys as well as ordinary characters.
Just as Lisp characters (actually integers) represent keyboard
characters, Lisp symbols represent function keys.  If the function key
has a word as its label, then that word is also the name of the
corresponding Lisp symbol.  Here are the conventional Lisp names for
common function keys:

`left', `up', `right', `down'
     Cursor arrow keys.

`begin', `end', `home', `next', `prior'
     Other cursor repositioning keys.

`select', `print', `execute', `backtab'
`insert', `undo', `redo', `clearline'
`insertline', `deleteline', `insertchar', `deletechar'
     Miscellaneous function keys.

`f1', `f2', ... `f35'
     Numbered function keys (across the top of the keyboard).

`kp-add', `kp-subtract', `kp-multiply', `kp-divide'
`kp-backtab', `kp-space', `kp-tab', `kp-enter'
`kp-separator', `kp-decimal', `kp-equal'
     Keypad keys (to the right of the regular keyboard), with names or
     punctuation.

`kp-0', `kp-1', ... `kp-9'
     Keypad keys with digits.

`kp-f1', `kp-f2', `kp-f3', `kp-f4'
     Keypad PF keys.

   These names are conventional, but some systems (especially when using
X) may use different names.  To make certain what symbol is used for a
given function key on your terminal, type `C-h c' followed by that key.

   *Note Init Rebinding::, for examples of binding function keys.

   Many keyboards have a "numeric keypad" on the right hand side.  The
numeric keys in the keypad double up as cursor motion keys, toggled by
a key labeled `Num Lock'.  By default, Emacs translates these keys to
the corresponding keys in the main keyboard.  For example, when `Num
Lock' is on, the key labeled `8' on the numeric keypad produces `kp-8',
which is translated to `8'; when `Num Lock' is off, the same key
produces `kp-up', which is translated to <UP>.  If you rebind a key
such as `8' or <UP>, it affects the equivalent keypad key too.
However, if you rebind a `kp-' key directly, that won't affect its
non-keypad equivalent.  Note that the modified keys are not translated:
for instance, if you hold down the <META> key while pressing the `8'
key on the numeric keypad, that generates `M-<kp-8>'.

   Emacs provides a convenient method for binding the numeric keypad
keys, using the variables `keypad-setup', `keypad-numlock-setup',
`keypad-shifted-setup', and `keypad-numlock-shifted-setup'.  These can
be found in the `keyboard' customization group (*note Easy
Customization::).  You can rebind the keys to perform other tasks, such
as issuing numeric prefix arguments.


File: emacs,  Node: Named ASCII Chars,  Next: Mouse Buttons,  Prev: Function Keys,  Up: Key Bindings

48.3.9 Named ASCII Control Characters
-------------------------------------

<TAB>, <RET>, <BS>, <LFD>, <ESC> and <DEL> started out as names for
certain ASCII control characters, used so often that they have special
keys of their own.  For instance, <TAB> was another name for `C-i'.
Later, users found it convenient to distinguish in Emacs between these
keys and the "same" control characters typed with the <CTRL> key.
Therefore, on most modern terminals, they are no longer the same: <TAB>
is different from `C-i'.

   Emacs can distinguish these two kinds of input if the keyboard does.
It treats the "special" keys as function keys named `tab', `return',
`backspace', `linefeed', `escape', and `delete'.  These function keys
translate automatically into the corresponding ASCII characters _if_
they have no bindings of their own.  As a result, neither users nor
Lisp programs need to pay attention to the distinction unless they care
to.

   If you do not want to distinguish between (for example) <TAB> and
`C-i', make just one binding, for the ASCII character <TAB> (octal code
011).  If you do want to distinguish, make one binding for this ASCII
character, and another for the "function key" `tab'.

   With an ordinary ASCII terminal, there is no way to distinguish
between <TAB> and `C-i' (and likewise for other such pairs), because
the terminal sends the same character in both cases.


File: emacs,  Node: Mouse Buttons,  Next: Disabling,  Prev: Named ASCII Chars,  Up: Key Bindings

48.3.10 Rebinding Mouse Buttons
-------------------------------

Emacs uses Lisp symbols to designate mouse buttons, too.  The ordinary
mouse events in Emacs are "click" events; these happen when you press a
button and release it without moving the mouse.  You can also get
"drag" events, when you move the mouse while holding the button down.
Drag events happen when you finally let go of the button.

   The symbols for basic click events are `mouse-1' for the leftmost
button, `mouse-2' for the next, and so on.  Here is how you can
redefine the second mouse button to split the current window:

     (global-set-key [mouse-2] 'split-window-below)

   The symbols for drag events are similar, but have the prefix `drag-'
before the word `mouse'.  For example, dragging the first button
generates a `drag-mouse-1' event.

   You can also define bindings for events that occur when a mouse
button is pressed down.  These events start with `down-' instead of
`drag-'.  Such events are generated only if they have key bindings.
When you get a button-down event, a corresponding click or drag event
will always follow.

   If you wish, you can distinguish single, double, and triple clicks.
A double click means clicking a mouse button twice in approximately the
same place.  The first click generates an ordinary click event.  The
second click, if it comes soon enough, generates a double-click event
instead.  The event type for a double-click event starts with
`double-': for example, `double-mouse-3'.

   This means that you can give a special meaning to the second click at
the same place, but it must act on the assumption that the ordinary
single click definition has run when the first click was received.

   This constrains what you can do with double clicks, but user
interface designers say that this constraint ought to be followed in
any case.  A double click should do something similar to the single
click, only "more so".  The command for the double-click event should
perform the extra work for the double click.

   If a double-click event has no binding, it changes to the
corresponding single-click event.  Thus, if you don't define a
particular double click specially, it executes the single-click command
twice.

   Emacs also supports triple-click events whose names start with
`triple-'.  Emacs does not distinguish quadruple clicks as event types;
clicks beyond the third generate additional triple-click events.
However, the full number of clicks is recorded in the event list, so if
you know Emacs Lisp you can distinguish if you really want to (*note
Click Events: (elisp)Click Events.).  We don't recommend distinct
meanings for more than three clicks, but sometimes it is useful for
subsequent clicks to cycle through the same set of three meanings, so
that four clicks are equivalent to one click, five are equivalent to
two, and six are equivalent to three.

   Emacs also records multiple presses in drag and button-down events.
For example, when you press a button twice, then move the mouse while
holding the button, Emacs gets a `double-drag-' event.  And at the
moment when you press it down for the second time, Emacs gets a
`double-down-' event (which is ignored, like all button-down events, if
it has no binding).

   The variable `double-click-time' specifies how much time can elapse
between clicks and still allow them to be grouped as a multiple click.
Its value is in units of milliseconds.  If the value is `nil', double
clicks are not detected at all.  If the value is `t', then there is no
time limit.  The default is 500.

   The variable `double-click-fuzz' specifies how much the mouse can
move between clicks and still allow them to be grouped as a multiple
click.  Its value is in units of pixels on windowed displays and in
units of 1/8 of a character cell on text-mode terminals; the default is
3.

   The symbols for mouse events also indicate the status of the modifier
keys, with the usual prefixes `C-', `M-', `H-', `s-', `A-' and `S-'.
These always precede `double-' or `triple-', which always precede
`drag-' or `down-'.

   A frame includes areas that don't show text from the buffer, such as
the mode line and the scroll bar.  You can tell whether a mouse button
comes from a special area of the screen by means of dummy "prefix
keys".  For example, if you click the mouse in the mode line, you get
the prefix key `mode-line' before the ordinary mouse-button symbol.
Thus, here is how to define the command for clicking the first button in
a mode line to run `scroll-up-command':

     (global-set-key [mode-line mouse-1] 'scroll-up-command)

   Here is the complete list of these dummy prefix keys and their
meanings:

`mode-line'
     The mouse was in the mode line of a window.

`vertical-line'
     The mouse was in the vertical line separating side-by-side
     windows.  (If you use scroll bars, they appear in place of these
     vertical lines.)

`vertical-scroll-bar'
     The mouse was in a vertical scroll bar.  (This is the only kind of
     scroll bar Emacs currently supports.)

`menu-bar'
     The mouse was in the menu bar.

`header-line'
     The mouse was in a header line.

   You can put more than one mouse button in a key sequence, but it
isn't usual to do so.


File: emacs,  Node: Disabling,  Prev: Mouse Buttons,  Up: Key Bindings

48.3.11 Disabling Commands
--------------------------

Disabling a command means that invoking it interactively asks for
confirmation from the user.  The purpose of disabling a command is to
prevent users from executing it by accident; we do this for commands
that might be confusing to the uninitiated.

   Attempting to invoke a disabled command interactively in Emacs
displays a window containing the command's name, its documentation, and
some instructions on what to do immediately; then Emacs asks for input
saying whether to execute the command as requested, enable it and
execute it, or cancel.  If you decide to enable the command, you must
then answer another question--whether to do this permanently, or just
for the current session.  (Enabling permanently works by automatically
editing your initialization file.)  You can also type `!' to enable
_all_ commands, for the current session only.

   The direct mechanism for disabling a command is to put a non-`nil'
`disabled' property on the Lisp symbol for the command.  Here is the
Lisp program to do this:

     (put 'delete-region 'disabled t)

   If the value of the `disabled' property is a string, that string is
included in the message displayed when the command is used:

     (put 'delete-region 'disabled
          "It's better to use `kill-region' instead.\n")

   You can make a command disabled either by editing the initialization
file directly, or with the command `M-x disable-command', which edits
the initialization file for you.  Likewise, `M-x enable-command' edits
the initialization file to enable a command permanently.  *Note Init
File::.

   If Emacs was invoked with the `-q' or `--no-init-file' options
(*note Initial Options::), it will not edit your initialization file.
Doing so could lose information because Emacs has not read your
initialization file.

   Whether a command is disabled is independent of what key is used to
invoke it; disabling also applies if the command is invoked using
`M-x'.  However, disabling a command has no effect on calling it as a
function from Lisp programs.


File: emacs,  Node: Init File,  Prev: Key Bindings,  Up: Customization

48.4 The Emacs Initialization File
==================================

When Emacs is started, it normally tries to load a Lisp program from an
"initialization file", or "init file" for short.  This file, if it
exists, specifies how to initialize Emacs for you.  Emacs looks for
your init file using the filenames `~/.emacs', `~/.emacs.el', or
`~/.emacs.d/init.el'; you can choose to use any one of these three
names (*note Find Init::).  Here, `~/' stands for your home directory.

   You can use the command line switch `-q' to prevent loading your
init file, and `-u' (or `--user') to specify a different user's init
file (*note Initial Options::).

   There can also be a "default init file", which is the library named
`default.el', found via the standard search path for libraries.  The
Emacs distribution contains no such library; your site may create one
for local customizations.  If this library exists, it is loaded
whenever you start Emacs (except when you specify `-q').  But your init
file, if any, is loaded first; if it sets `inhibit-default-init'
non-`nil', then `default' is not loaded.

   Your site may also have a "site startup file"; this is named
`site-start.el', if it exists.  Like `default.el', Emacs finds this
file via the standard search path for Lisp libraries.  Emacs loads this
library before it loads your init file.  To inhibit loading of this
library, use the option `--no-site-file'.  *Note Initial Options::.  We
recommend against using `site-start.el' for changes that some users may
not like.  It is better to put them in `default.el', so that users can
more easily override them.

   You can place `default.el' and `site-start.el' in any of the
directories which Emacs searches for Lisp libraries.  The variable
`load-path' (*note Lisp Libraries::) specifies these directories.  Many
sites put these files in the `site-lisp' subdirectory of the Emacs
installation directory, typically `/usr/local/share/emacs/site-lisp'.

   Byte-compiling your init file is not recommended (*note Byte
Compilation: (elisp)Byte Compilation.).  It generally does not speed up
startup very much, and often leads to problems when you forget to
recompile the file.  A better solution is to use the Emacs server to
reduce the number of times you have to start Emacs (*note Emacs
Server::).  If your init file defines many functions, consider moving
them to a separate (byte-compiled) file that you load in your init file.

   If you are going to write actual Emacs Lisp programs that go beyond
minor customization, you should read the `Emacs Lisp Reference Manual'.
*Note Emacs Lisp: (elisp)Top.

* Menu:

* Init Syntax::         Syntax of constants in Emacs Lisp.
* Init Examples::       How to do some things with an init file.
* Terminal Init::       Each terminal type can have an init file.
* Find Init::           How Emacs finds the init file.
* Init Non-ASCII::      Using non-ASCII characters in an init file.


File: emacs,  Node: Init Syntax,  Next: Init Examples,  Up: Init File

48.4.1 Init File Syntax
-----------------------

The init file contains one or more Lisp expressions.  Each of these
consists of a function name followed by arguments, all surrounded by
parentheses.  For example, `(setq fill-column 60)' calls the function
`setq' to set the variable `fill-column' (*note Filling::) to 60.

   You can set any Lisp variable with `setq', but with certain
variables `setq' won't do what you probably want in the `.emacs' file.
Some variables automatically become buffer-local when set with `setq';
what you want in `.emacs' is to set the default value, using
`setq-default'.  Some customizable minor mode variables do special
things to enable the mode when you set them with Customize, but
ordinary `setq' won't do that; to enable the mode in your `.emacs'
file, call the minor mode command.  The following section has examples
of both of these methods.

   The second argument to `setq' is an expression for the new value of
the variable.  This can be a constant, a variable, or a function call
expression.  In `.emacs', constants are used most of the time.  They
can be:

Numbers:
     Numbers are written in decimal, with an optional initial minus
     sign.

Strings:
     Lisp string syntax is the same as C string syntax with a few extra
     features.  Use a double-quote character to begin and end a string
     constant.

     In a string, you can include newlines and special characters
     literally.  But often it is cleaner to use backslash sequences for
     them: `\n' for newline, `\b' for backspace, `\r' for carriage
     return, `\t' for tab, `\f' for formfeed (control-L), `\e' for
     escape, `\\' for a backslash, `\"' for a double-quote, or `\OOO'
     for the character whose octal code is OOO.  Backslash and
     double-quote are the only characters for which backslash sequences
     are mandatory.

     `\C-' can be used as a prefix for a control character, as in
     `\C-s' for ASCII control-S, and `\M-' can be used as a prefix for
     a Meta character, as in `\M-a' for `Meta-A' or `\M-\C-a' for
     `Control-Meta-A'.

     *Note Init Non-ASCII::, for information about including non-ASCII
     in your init file.

Characters:
     Lisp character constant syntax consists of a `?' followed by
     either a character or an escape sequence starting with `\'.
     Examples: `?x', `?\n', `?\"', `?\)'.  Note that strings and
     characters are not interchangeable in Lisp; some contexts require
     one and some contexts require the other.

     *Note Init Non-ASCII::, for information about binding commands to
     keys which send non-ASCII characters.

True:
     `t' stands for `true'.

False:
     `nil' stands for `false'.

Other Lisp objects:
     Write a single-quote (`'') followed by the Lisp object you want.



Local Variables:
coding: iso-8859-1
End:
